@indigoai-us/hq-cloud 6.14.16 → 6.14.18

package/dist/manifest-reconcile.test.js

@@ -3,7 +3,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import yaml from "js-yaml";
-import { reconcileCompanyManifest } from "./manifest-reconcile.js";
+import { reconcileCompanyManifest, reconcileManifest, } from "./manifest-reconcile.js";
+import { VaultNotFoundError, VaultPermissionDeniedError, } from "./vault-client.js";
 let hqRoot;
 afterEach(() => {
     if (hqRoot) {
@@ -11,6 +12,448 @@ afterEach(() => {
         hqRoot = undefined;
     }
 });
+/** The stock manifest shipped to a fresh HQ root: header comment, no companies. */
+const EMPTY_MANIFEST_TEMPLATE = `# HQ company manifest.
+# Source of truth for which company slugs this HQ root routes.
+# Edited by humans; reconciled by hq-sync. Keep this header.
+companies: {}
+`;
+/** Far enough in the past that any rewrite is unmistakable in the mtime. */
+const FROZEN_MTIME = new Date("2020-01-01T00:00:00.000Z");
+function makeHqRoot() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-reconcile-"));
+    fs.mkdirSync(path.join(root, "companies"), { recursive: true });
+    return root;
+}
+function manifestPathFor(root) {
+    return path.join(root, "companies", "manifest.yaml");
+}
+function writeManifest(root, contents) {
+    const manifestPath = manifestPathFor(root);
+    fs.writeFileSync(manifestPath, contents, "utf8");
+    fs.utimesSync(manifestPath, FROZEN_MTIME, FROZEN_MTIME);
+    return manifestPath;
+}
+function readCompanies(manifestPath) {
+    const parsed = yaml.load(fs.readFileSync(manifestPath, "utf8"));
+    return parsed.companies ?? {};
+}
+/** Asserts the file was not touched at all — contents AND mtime. */
+function expectUntouched(manifestPath, before) {
+    expect(fs.readFileSync(manifestPath, "utf8")).toBe(before);
+    expect(fs.statSync(manifestPath).mtimeMs).toBe(FROZEN_MTIME.getTime());
+}
+describe("reconcileManifest", () => {
+    it("inserts a company into the stock empty manifest template", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const result = reconcileManifest(hqRoot, [
+            {
+                slug: "acme",
+                uid: "cmp_acme",
+                name: "Acme Inc",
+                bucketName: "hq-vault-cmp-acme",
+            },
+        ]);
+        expect(result).toEqual({
+            written: true,
+            added: ["acme"],
+            updated: [],
+            skipped: [],
+        });
+        expect(readCompanies(manifestPath)).toEqual({
+            acme: {
+                cloud_uid: "cmp_acme",
+                name: "Acme Inc",
+                bucket_name: "hq-vault-cmp-acme",
+            },
+        });
+    });
+    it("inserts alongside an existing company without disturbing it", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, `version: 3\ncompanies:\n  incumbent:\n    name: Incumbent\n    cloud_uid: cmp_incumbent\n    bucket_name: hq-vault-cmp-incumbent\n`);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "joiner", uid: "cmp_joiner", name: "Joiner", bucketName: "hq-vault-cmp-joiner" },
+        ]);
+        expect(result.written).toBe(true);
+        expect(result.added).toEqual(["joiner"]);
+        expect(result.updated).toEqual([]);
+        expect(readCompanies(manifestPath)).toEqual({
+            incumbent: {
+                name: "Incumbent",
+                cloud_uid: "cmp_incumbent",
+                bucket_name: "hq-vault-cmp-incumbent",
+            },
+            joiner: {
+                cloud_uid: "cmp_joiner",
+                name: "Joiner",
+                bucket_name: "hq-vault-cmp-joiner",
+            },
+        });
+        // Unrelated top-level state survives the merge.
+        expect(yaml.load(fs.readFileSync(manifestPath, "utf8")).version).toBe(3);
+    });
+    it("performs no write at all when every target is already current", () => {
+        hqRoot = makeHqRoot();
+        // The header comment is the canary: js-yaml cannot round-trip comments, so
+        // any rewrite would silently drop it and churn the personal-vault copy.
+        const contents = `# Keep this header comment.\ncompanies:\n  acme:\n    name: Acme Inc\n    cloud_uid: cmp_acme\n    bucket_name: hq-vault-cmp-acme\n`;
+        const manifestPath = writeManifest(hqRoot, contents);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "acme", uid: "cmp_acme", name: "Acme Inc", bucketName: "hq-vault-cmp-acme" },
+        ]);
+        expect(result).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expectUntouched(manifestPath, contents);
+        expect(fs.readFileSync(manifestPath, "utf8")).toContain("# Keep this header comment.");
+    });
+    it("reports a partial drift as an update and leaves untouched fields alone", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, `companies:\n  acme:\n    name: Acme Inc\n    cloud_uid: cmp_acme\n    bucket_name: hq-vault-stale\n`);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "acme", uid: "cmp_acme", name: "Acme Inc", bucketName: "hq-vault-cmp-acme" },
+        ]);
+        expect(result).toEqual({
+            written: true,
+            added: [],
+            updated: ["acme"],
+            skipped: [],
+        });
+        expect(readCompanies(manifestPath).acme).toEqual({
+            name: "Acme Inc",
+            cloud_uid: "cmp_acme",
+            bucket_name: "hq-vault-cmp-acme",
+        });
+    });
+    it("preserves unknown keys on both the untouched and the updated company", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, [
+            "companies:",
+            "  bystander:",
+            "    name: Bystander",
+            "    cloud_uid: cmp_bystander",
+            "    repos:",
+            "      - repos/private/bystander",
+            "    workers:",
+            "      - designer",
+            "    qmd_collections:",
+            "      - bystander-docs",
+            "  acme:",
+            "    name: Acme Inc",
+            "    cloud_uid: cmp_acme",
+            "    bucket_name: hq-vault-stale",
+            "    repos:",
+            "      - repos/private/acme",
+            "    workers:",
+            "      - backend-dev",
+            "    qmd_collections:",
+            "      - acme-docs",
+            "",
+        ].join("\n"));
+        const result = reconcileManifest(hqRoot, [
+            { slug: "acme", uid: "cmp_acme", name: "Acme Inc", bucketName: "hq-vault-cmp-acme" },
+        ]);
+        expect(result.updated).toEqual(["acme"]);
+        const companies = readCompanies(manifestPath);
+        expect(companies.bystander).toEqual({
+            name: "Bystander",
+            cloud_uid: "cmp_bystander",
+            repos: ["repos/private/bystander"],
+            workers: ["designer"],
+            qmd_collections: ["bystander-docs"],
+        });
+        expect(companies.acme).toEqual({
+            name: "Acme Inc",
+            cloud_uid: "cmp_acme",
+            bucket_name: "hq-vault-cmp-acme",
+            repos: ["repos/private/acme"],
+            workers: ["backend-dev"],
+            qmd_collections: ["acme-docs"],
+        });
+    });
+    it("no-ops without throwing when the manifest cannot be parsed", () => {
+        hqRoot = makeHqRoot();
+        const contents = "companies:\n  acme:\n   - this: is\n  not: valid yaml\n\t\tbad indent\n";
+        const manifestPath = writeManifest(hqRoot, contents);
+        let result;
+        expect(() => {
+            result = reconcileManifest(hqRoot, [
+                { slug: "acme", uid: "cmp_acme", name: "Acme Inc", bucketName: "hq-vault-cmp-acme" },
+            ]);
+        }).not.toThrow();
+        expect(result).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expectUntouched(manifestPath, contents);
+    });
+    it("no-ops when the manifest is missing and never creates one", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = manifestPathFor(hqRoot);
+        expect(fs.existsSync(manifestPath)).toBe(false);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "acme", uid: "cmp_acme", name: "Acme Inc", bucketName: "hq-vault-cmp-acme" },
+        ]);
+        expect(result).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expect(fs.existsSync(manifestPath)).toBe(false);
+    });
+    it("no-ops when `companies` is present but is not a mapping", () => {
+        hqRoot = makeHqRoot();
+        const contents = "companies:\n  - acme\n  - beta\n";
+        const manifestPath = writeManifest(hqRoot, contents);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "acme", uid: "cmp_acme", name: "Acme Inc", bucketName: "hq-vault-cmp-acme" },
+        ]);
+        expect(result.written).toBe(false);
+        expectUntouched(manifestPath, contents);
+    });
+    it("skips a slug whose existing entry is not a mapping", () => {
+        hqRoot = makeHqRoot();
+        const contents = "companies:\n  acme: not-a-mapping\n";
+        const manifestPath = writeManifest(hqRoot, contents);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "acme", uid: "cmp_acme", name: "Acme Inc", bucketName: "hq-vault-cmp-acme" },
+        ]);
+        expect(result).toEqual({ written: false, added: [], updated: [], skipped: ["acme"] });
+        expectUntouched(manifestPath, contents);
+    });
+    describe("path traversal guard", () => {
+        const unsafeSlugs = [
+            ["a forward-slash path", "nested/evil"],
+            ["a backslash path", "nested\\evil"],
+            ["the current directory", "."],
+            ["the parent directory", ".."],
+            ["a slug resolving outside the companies dir", "../escape"],
+            ["an empty slug", ""],
+            ["the __proto__ prototype key", "__proto__"],
+            ["the constructor prototype key", "constructor"],
+            ["the prototype prototype key", "prototype"],
+        ];
+        for (const [label, slug] of unsafeSlugs) {
+            it(`rejects ${label} without writing`, () => {
+                hqRoot = makeHqRoot();
+                const contents = EMPTY_MANIFEST_TEMPLATE;
+                const manifestPath = writeManifest(hqRoot, contents);
+                const result = reconcileManifest(hqRoot, [
+                    { slug, uid: "cmp_evil", name: "Evil", bucketName: "hq-vault-cmp-evil" },
+                ]);
+                expect(result.skipped).toEqual([slug]);
+                expect(result.written).toBe(false);
+                expect(result.added).toEqual([]);
+                expect(result.updated).toEqual([]);
+                expectUntouched(manifestPath, contents);
+                expect(readCompanies(manifestPath)).toEqual({});
+            });
+        }
+    });
+    it("does not fall into a write loop on a __proto__ slug", () => {
+        // Regression: `__proto__` read back as Object.prototype, so it passed the
+        // non-mapping skip, always reported drift, and never persisted through
+        // yaml.dump — a rewrite on every run of a vault-synced file, forever.
+        hqRoot = makeHqRoot();
+        const contents = EMPTY_MANIFEST_TEMPLATE;
+        const manifestPath = writeManifest(hqRoot, contents);
+        const targets = [{ slug: "__proto__", uid: "cmp_evil", name: "Evil" }];
+        for (let run = 0; run < 3; run += 1) {
+            const result = reconcileManifest(hqRoot, targets);
+            expect(result.written).toBe(false);
+            expect(result.skipped).toEqual(["__proto__"]);
+            expectUntouched(manifestPath, contents);
+        }
+        // The prototype itself must be clean — no pollution leaked out.
+        expect({}.cloud_uid).toBeUndefined();
+        expect(readCompanies(manifestPath)).toEqual({});
+    });
+    it("no-ops when `companies` is a timestamp scalar rather than a mapping", () => {
+        // js-yaml parses this into a Date, which a `typeof value === "object"`
+        // check would have accepted as the company map.
+        hqRoot = makeHqRoot();
+        const contents = "companies: 2026-01-01\n";
+        const manifestPath = writeManifest(hqRoot, contents);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "acme", uid: "cmp_acme", name: "Acme Inc", bucketName: "hq-vault-cmp-acme" },
+        ]);
+        expect(result).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expectUntouched(manifestPath, contents);
+    });
+    it("no-ops when `companies` is a plain string scalar", () => {
+        hqRoot = makeHqRoot();
+        const contents = "companies: nonsense\n";
+        const manifestPath = writeManifest(hqRoot, contents);
+        expect(reconcileManifest(hqRoot, [{ slug: "acme", uid: "cmp_acme" }]).written).toBe(false);
+        expectUntouched(manifestPath, contents);
+    });
+    it("skips a timestamp entry without destroying its value", () => {
+        // A Date entry used to slip past the non-mapping skip and then be silently
+        // flattened to {} by the object spread.
+        hqRoot = makeHqRoot();
+        const contents = "companies:\n  acme: 2026-01-01\n";
+        const manifestPath = writeManifest(hqRoot, contents);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "acme", uid: "cmp_acme", name: "Acme Inc", bucketName: "hq-vault-cmp-acme" },
+        ]);
+        expect(result).toEqual({ written: false, added: [], updated: [], skipped: ["acme"] });
+        expectUntouched(manifestPath, contents);
+    });
+    it("treats a bare `companies:` key as an empty map and inserts into it", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, "version: 3\ncompanies:\n");
+        const result = reconcileManifest(hqRoot, [{ slug: "acme", uid: "cmp_acme" }]);
+        expect(result.written).toBe(true);
+        expect(result.added).toEqual(["acme"]);
+        expect(readCompanies(manifestPath)).toEqual({ acme: { cloud_uid: "cmp_acme" } });
+    });
+    it("does not write when duplicate slugs produce no net change", () => {
+        // Regression: a sticky change flag was flipped on by the first target and
+        // back off by the second, leaving it true while content was identical.
+        hqRoot = makeHqRoot();
+        const contents = "companies:\n  acme:\n    cloud_uid: cmp_b\n";
+        const manifestPath = writeManifest(hqRoot, contents);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "acme", uid: "cmp_a" },
+            { slug: "acme", uid: "cmp_b" },
+        ]);
+        expect(result.written).toBe(false);
+        expect(result.updated).toEqual([]);
+        expectUntouched(manifestPath, contents);
+    });
+    it("applies last-wins for duplicate slugs that do change the file", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "acme", uid: "cmp_a" },
+            { slug: "acme", uid: "cmp_b" },
+        ]);
+        expect(result.written).toBe(true);
+        expect(result.added).toEqual(["acme"]);
+        expect(readCompanies(manifestPath)).toEqual({ acme: { cloud_uid: "cmp_b" } });
+    });
+    it("leaves no temp file behind when the write fails", () => {
+        hqRoot = makeHqRoot();
+        const companiesDir = path.join(hqRoot, "companies");
+        writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        // Read-only directory: the temp write itself fails, and on platforms where
+        // it does not, the rename over the target does.
+        fs.chmodSync(companiesDir, 0o500);
+        try {
+            expect(() => reconcileManifest(hqRoot, [{ slug: "acme", uid: "cmp_acme" }])).toThrow();
+            const strays = fs.readdirSync(companiesDir).filter((n) => n.startsWith(".manifest-"));
+            expect(strays).toEqual([]);
+        }
+        finally {
+            fs.chmodSync(companiesDir, 0o700);
+        }
+    });
+    it("documents that the first genuine write drops the manifest header comment", () => {
+        // yaml.dump cannot round-trip comments. This loss is accepted and is exactly
+        // why skip-if-unchanged must prevent every needless rewrite.
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        expect(fs.readFileSync(manifestPath, "utf8")).toContain("# HQ company manifest.");
+        expect(reconcileManifest(hqRoot, [{ slug: "acme", uid: "cmp_acme" }]).written).toBe(true);
+        const after = fs.readFileSync(manifestPath, "utf8");
+        expect(after).not.toContain("# HQ company manifest.");
+        // ...and the very next run must not touch it again.
+        const replay = reconcileManifest(hqRoot, [{ slug: "acme", uid: "cmp_acme" }]);
+        expect(replay.written).toBe(false);
+        expect(fs.readFileSync(manifestPath, "utf8")).toBe(after);
+    });
+    it("omits bucket_name entirely when the target has no bucket", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "joiner", uid: "cmp_joiner", name: "Joiner Inc" },
+        ]);
+        expect(result.added).toEqual(["joiner"]);
+        const entry = readCompanies(manifestPath).joiner;
+        expect("bucket_name" in entry).toBe(false);
+        expect(entry).toEqual({ cloud_uid: "cmp_joiner", name: "Joiner Inc" });
+        expect(fs.readFileSync(manifestPath, "utf8")).not.toContain("bucket_name");
+    });
+    it("omits name entirely when the target has no name", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "joiner", uid: "cmp_joiner", bucketName: "hq-vault-cmp-joiner" },
+        ]);
+        expect(result.added).toEqual(["joiner"]);
+        const entry = readCompanies(manifestPath).joiner;
+        expect("name" in entry).toBe(false);
+        expect(entry).toEqual({ cloud_uid: "cmp_joiner", bucket_name: "hq-vault-cmp-joiner" });
+        // No `name:` key line at all (`bucket_name:` must not satisfy this).
+        expect(fs.readFileSync(manifestPath, "utf8")).not.toMatch(/^\s*name:/m);
+    });
+    it("treats empty-string name and bucket as absent rather than writing blanks", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const result = reconcileManifest(hqRoot, [
+            { slug: "joiner", uid: "cmp_joiner", name: "", bucketName: "" },
+        ]);
+        expect(result).toEqual({
+            written: true,
+            added: ["joiner"],
+            updated: [],
+            skipped: [],
+        });
+        const entry = readCompanies(manifestPath).joiner;
+        expect("name" in entry).toBe(false);
+        expect("bucket_name" in entry).toBe(false);
+        expect(entry).toEqual({ cloud_uid: "cmp_joiner" });
+        // An empty-string field must not read as drift on the replay, or the
+        // manifest would be rewritten on every run.
+        fs.utimesSync(manifestPath, FROZEN_MTIME, FROZEN_MTIME);
+        const replay = reconcileManifest(hqRoot, [
+            { slug: "joiner", uid: "cmp_joiner", name: "", bucketName: "" },
+        ]);
+        expect(replay.written).toBe(false);
+        expect(fs.statSync(manifestPath).mtimeMs).toBe(FROZEN_MTIME.getTime());
+    });
+    it("still writes cloud_uid for a company that has neither name nor bucket", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const result = reconcileManifest(hqRoot, [{ slug: "joiner", uid: "cmp_joiner" }]);
+        expect(result.written).toBe(true);
+        expect(result.added).toEqual(["joiner"]);
+        expect(readCompanies(manifestPath).joiner).toEqual({ cloud_uid: "cmp_joiner" });
+    });
+    it("never deletes an existing key just because the target omits it", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, `companies:\n  acme:\n    name: Acme Inc\n    cloud_uid: cmp_old\n    bucket_name: hq-vault-cmp-acme\n`);
+        const result = reconcileManifest(hqRoot, [{ slug: "acme", uid: "cmp_acme" }]);
+        expect(result.updated).toEqual(["acme"]);
+        expect(readCompanies(manifestPath).acme).toEqual({
+            name: "Acme Inc",
+            cloud_uid: "cmp_acme",
+            bucket_name: "hq-vault-cmp-acme",
+        });
+    });
+    it("reports adds, updates and skips together in one pass", () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, [
+            "companies:",
+            "  current:",
+            "    cloud_uid: cmp_current",
+            "  drifted:",
+            "    cloud_uid: cmp_stale",
+            "  broken: not-a-mapping",
+            "",
+        ].join("\n"));
+        const result = reconcileManifest(hqRoot, [
+            { slug: "fresh", uid: "cmp_fresh" },
+            { slug: "drifted", uid: "cmp_drifted" },
+            { slug: "current", uid: "cmp_current" },
+            { slug: "broken", uid: "cmp_broken" },
+            { slug: "../escape", uid: "cmp_escape" },
+        ]);
+        expect(result).toEqual({
+            written: true,
+            added: ["fresh"],
+            updated: ["drifted"],
+            skipped: ["../escape", "broken"],
+        });
+        const companies = readCompanies(manifestPath);
+        expect(companies.current).toEqual({ cloud_uid: "cmp_current" });
+        expect(companies.drifted).toEqual({ cloud_uid: "cmp_drifted" });
+        expect(companies.fresh).toEqual({ cloud_uid: "cmp_fresh" });
+        expect(companies.broken).toBe("not-a-mapping");
+    });
+});
 describe("reconcileCompanyManifest", () => {
     it("atomically restores one successful cloud entry after the personal leg without replacing existing manifest state", async () => {
         hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-reconcile-"));
@@ -71,8 +514,14 @@ describe("reconcileCompanyManifest", () => {
         };
         await reconcileCompanyManifest(options);
         const firstWrite = fs.readFileSync(manifestPath, "utf8");
-        await reconcileCompanyManifest(options);
+        // Freeze the mtime so the replay cannot pass by coincidence: identical bytes
+        // written a second time would still bump mtime, and mtime is what the sync
+        // layer keys on, so a byte comparison alone would miss a real conflict loop.
+        fs.utimesSync(manifestPath, FROZEN_MTIME, FROZEN_MTIME);
+        const replay = await reconcileCompanyManifest(options);
+        expect(replay.written).toBe(false);
         expect(fs.readFileSync(manifestPath, "utf8")).toBe(firstWrite);
+        expect(fs.statSync(manifestPath).mtimeMs).toBe(FROZEN_MTIME.getTime());
         expect(yaml.load(firstWrite)).toEqual({
             version: 3,
             settings: { keep: true },
@@ -93,5 +542,378 @@ describe("reconcileCompanyManifest", () => {
             },
         });
     });
+    it("returns the reconcile result on the insert path and again on the no-op replay", async () => {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "acme"), { recursive: true });
+        writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const options = {
+            hqRoot,
+            targets: [{ uid: "cmp_acme", slug: "acme" }],
+            completedCompanySlugs: new Set(["acme"]),
+            getEntity: async () => ({
+                uid: "cmp_acme",
+                slug: "acme",
+                type: "company",
+                status: "active",
+                name: "Acme Inc",
+                bucketName: "hq-vault-cmp-acme",
+                createdAt: "2026-01-01T00:00:00Z",
+            }),
+        };
+        expect(await reconcileCompanyManifest(options)).toEqual({
+            written: true,
+            added: ["acme"],
+            updated: [],
+            skipped: [],
+        });
+        expect(await reconcileCompanyManifest(options)).toEqual({
+            written: false,
+            added: [],
+            updated: [],
+            skipped: [],
+        });
+    });
+    it("returns an empty result when no target is eligible", async () => {
+        hqRoot = makeHqRoot();
+        writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        expect(await reconcileCompanyManifest({
+            hqRoot,
+            targets: [{ uid: "prs_me", slug: "personal", personalMode: true }],
+            completedCompanySlugs: new Set(["personal"]),
+            getEntity: async () => {
+                throw new Error("should not be called");
+            },
+        })).toEqual({ written: false, added: [], updated: [], skipped: [] });
+    });
+    it("keeps a company that has no name or bucket instead of dropping it", async () => {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "joiner"), { recursive: true });
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const options = {
+            hqRoot,
+            targets: [{ uid: "cmp_joiner", slug: "joiner" }],
+            completedCompanySlugs: new Set(["joiner"]),
+            getEntity: async () => ({
+                uid: "cmp_joiner",
+                slug: "joiner",
+                type: "company",
+                status: "active",
+                createdAt: "2026-01-01T00:00:00Z",
+            }),
+        };
+        const result = await reconcileCompanyManifest(options);
+        expect(result.written).toBe(true);
+        expect(result.added).toEqual(["joiner"]);
+        const entry = readCompanies(manifestPath).joiner;
+        expect(entry).toEqual({ cloud_uid: "cmp_joiner" });
+        expect("name" in entry).toBe(false);
+        expect("bucket_name" in entry).toBe(false);
+        // The highest-risk idempotency property: a target missing both optional
+        // fields must not re-report drift forever.
+        const after = fs.readFileSync(manifestPath, "utf8");
+        const mtime = fs.statSync(manifestPath).mtimeMs;
+        expect((await reconcileCompanyManifest(options)).written).toBe(false);
+        expect((await reconcileCompanyManifest(options)).written).toBe(false);
+        expect(fs.readFileSync(manifestPath, "utf8")).toBe(after);
+        expect(fs.statSync(manifestPath).mtimeMs).toBe(mtime);
+    });
+    // -------------------------------------------------------------------------
+    // US-002 — plan-carried path (no `getEntity`). This is the shape the
+    // sync-runner uses: `buildFanoutPlan` already resolved the entity, so the
+    // reconciler makes zero API calls and reads name/bucketName off the target.
+    // -------------------------------------------------------------------------
+    it("without getEntity: writes entries straight from the plan-carried target fields", async () => {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "acme"), { recursive: true });
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const options = {
+            hqRoot,
+            targets: [
+                {
+                    uid: "cmp_acme",
+                    slug: "acme",
+                    name: "Acme Inc",
+                    bucketName: "hq-vault-cmp-acme",
+                    entityType: "company",
+                    entityStatus: "active",
+                },
+            ],
+            completedCompanySlugs: new Set(["acme"]),
+        };
+        expect(await reconcileCompanyManifest(options)).toEqual({
+            written: true,
+            added: ["acme"],
+            updated: [],
+            skipped: [],
+        });
+        expect(readCompanies(manifestPath).acme).toEqual({
+            cloud_uid: "cmp_acme",
+            name: "Acme Inc",
+            bucket_name: "hq-vault-cmp-acme",
+        });
+        // Same idempotency contract as the getEntity path.
+        const after = fs.readFileSync(manifestPath, "utf8");
+        fs.utimesSync(manifestPath, FROZEN_MTIME, FROZEN_MTIME);
+        expect((await reconcileCompanyManifest(options)).written).toBe(false);
+        expectUntouched(manifestPath, after);
+    });
+    it("without getEntity: still writes a target that carries neither name nor bucketName", async () => {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "joiner"), { recursive: true });
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const result = await reconcileCompanyManifest({
+            hqRoot,
+            targets: [
+                {
+                    uid: "cmp_joiner",
+                    slug: "joiner",
+                    entityType: "company",
+                    entityStatus: "active",
+                },
+            ],
+            completedCompanySlugs: new Set(["joiner"]),
+        });
+        expect(result.written).toBe(true);
+        expect(readCompanies(manifestPath).joiner).toEqual({ cloud_uid: "cmp_joiner" });
+    });
+    it("without getEntity: keeps every eligibility filter — personal, incomplete, and unmaterialized targets are skipped", async () => {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "acme"), { recursive: true });
+        fs.mkdirSync(path.join(hqRoot, "companies", "incomplete"), { recursive: true });
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const result = await reconcileCompanyManifest({
+            hqRoot,
+            targets: [
+                {
+                    uid: "cmp_acme",
+                    slug: "acme",
+                    bucketName: "hq-vault-cmp-acme",
+                    entityType: "company",
+                    entityStatus: "active",
+                },
+                // Completed and live, but never materialized a directory on disk.
+                {
+                    uid: "cmp_ghost",
+                    slug: "ghost",
+                    bucketName: "hq-vault-cmp-ghost",
+                    entityType: "company",
+                    entityStatus: "active",
+                },
+                // On disk and live, but its fanout leg did not complete.
+                {
+                    uid: "cmp_incomplete",
+                    slug: "incomplete",
+                    entityType: "company",
+                    entityStatus: "active",
+                },
+                // Personal vault — never a manifest entry, even if it completed.
+                { uid: "prs_me", slug: "personal", personalMode: true },
+            ],
+            completedCompanySlugs: new Set(["acme", "ghost", "personal"]),
+        });
+        expect(result).toEqual({
+            written: true,
+            added: ["acme"],
+            updated: [],
+            skipped: [],
+        });
+        expect(Object.keys(readCompanies(manifestPath))).toEqual(["acme"]);
+    });
+    // Removing the per-target `entity.get` round trip (US-002) must not remove the
+    // liveness GUARANTEE it provided. Without an entity resolver the only evidence
+    // left is what the plan captured, so a target that cannot prove it was an
+    // active company at plan time must fail closed.
+    // Entity-probe failures all skip the target, but they are not all equally
+    // routine. "The company is gone" is expected; "the resolver is broken" is the
+    // failure mode that would otherwise masquerade as "joiners never get manifest
+    // entries" — the exact bug this module exists to prevent.
+    it("stays silent when a probe fails for the ordinary reasons (404 / 403)", async () => {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "gone"), { recursive: true });
+        fs.mkdirSync(path.join(hqRoot, "companies", "forbidden"), { recursive: true });
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const diagnostics = [];
+        const result = await reconcileCompanyManifest({
+            hqRoot,
+            targets: [
+                { uid: "cmp_gone", slug: "gone" },
+                { uid: "cmp_forbidden", slug: "forbidden" },
+            ],
+            completedCompanySlugs: new Set(["gone", "forbidden"]),
+            getEntity: (uid) => uid === "cmp_gone"
+                ? Promise.reject(new VaultNotFoundError("company deleted"))
+                : Promise.reject(new VaultPermissionDeniedError("no longer a member")),
+            reportDiagnostic: (d) => diagnostics.push(d),
+        });
+        expect(result).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expect(diagnostics).toEqual([]);
+        expectUntouched(manifestPath, EMPTY_MANIFEST_TEMPLATE);
+    });
+    it("reports an unexpected probe failure instead of silently skipping the target", async () => {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "acme"), { recursive: true });
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const diagnostics = [];
+        const result = await reconcileCompanyManifest({
+            hqRoot,
+            targets: [{ uid: "cmp_acme", slug: "acme" }],
+            completedCompanySlugs: new Set(["acme"]),
+            // A programming error, not a lookup answer.
+            getEntity: () => Promise.reject(new TypeError("resolver is not a function")),
+            reportDiagnostic: (d) => diagnostics.push(d),
+        });
+        // The target is still skipped — a broken probe never mints an entry.
+        expect(result).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expectUntouched(manifestPath, EMPTY_MANIFEST_TEMPLATE);
+        // ...but it is no longer invisible.
+        expect(diagnostics).toHaveLength(1);
+        expect(diagnostics[0].event).toBe("runner.manifest_reconcile.entity_probe_failed");
+        expect(diagnostics[0].err).toBeInstanceOf(TypeError);
+        expect(diagnostics[0].context).toMatchObject({ slug: "acme", uid: "cmp_acme" });
+    });
+    it("without getEntity: fails closed when the plan carried no liveness evidence at all", async () => {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "gone"), { recursive: true });
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        expect(await reconcileCompanyManifest({
+            hqRoot,
+            // Completed, non-personal, directory on disk — every OTHER filter passes.
+            targets: [{ uid: "cmp_deleted", slug: "gone" }],
+            completedCompanySlugs: new Set(["gone"]),
+        })).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expect(readCompanies(manifestPath).gone).toBeUndefined();
+        expectUntouched(manifestPath, EMPTY_MANIFEST_TEMPLATE);
+    });
+    it("without getEntity: refuses a target the plan saw as non-active or non-company", async () => {
+        hqRoot = makeHqRoot();
+        for (const slug of ["suspended", "deleted", "notacompany"]) {
+            fs.mkdirSync(path.join(hqRoot, "companies", slug), { recursive: true });
+        }
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        expect(await reconcileCompanyManifest({
+            hqRoot,
+            targets: [
+                {
+                    uid: "cmp_suspended",
+                    slug: "suspended",
+                    entityType: "company",
+                    entityStatus: "suspended",
+                },
+                {
+                    uid: "cmp_deleted",
+                    slug: "deleted",
+                    entityType: "company",
+                    entityStatus: "deleted",
+                },
+                {
+                    uid: "prs_person",
+                    slug: "notacompany",
+                    entityType: "person",
+                    entityStatus: "active",
+                },
+            ],
+            completedCompanySlugs: new Set(["suspended", "deleted", "notacompany"]),
+        })).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expect(Object.keys(readCompanies(manifestPath))).toEqual([]);
+        expectUntouched(manifestPath, EMPTY_MANIFEST_TEMPLATE);
+    });
+    it("without getEntity: no eligible target means no write at all", async () => {
+        hqRoot = makeHqRoot();
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        expect(await reconcileCompanyManifest({
+            hqRoot,
+            targets: [{ uid: "prs_me", slug: "personal", personalMode: true }],
+            completedCompanySlugs: new Set(["personal"]),
+        })).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expectUntouched(manifestPath, EMPTY_MANIFEST_TEMPLATE);
+    });
+    async function reconcileWithProbeError(err) {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "acme"), { recursive: true });
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        const diagnostics = [];
+        const result = await reconcileCompanyManifest({
+            hqRoot,
+            targets: [{ uid: "cmp_acme", slug: "acme" }],
+            completedCompanySlugs: new Set(["acme"]),
+            getEntity: () => Promise.reject(err),
+            reportDiagnostic: (diagnostic) => diagnostics.push(diagnostic),
+        });
+        // Invariant across every case: skipped, nothing written, file untouched.
+        expect(result).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expectUntouched(manifestPath, EMPTY_MANIFEST_TEMPLATE);
+        return { diagnostics, manifestPath };
+    }
+    it("with getEntity: a broken resolver (TypeError) is skipped AND reported", async () => {
+        const { diagnostics } = await reconcileWithProbeError(new TypeError("client.entity.get is not a function"));
+        expect(diagnostics).toHaveLength(1);
+        expect(diagnostics[0].event).toBe("runner.manifest_reconcile.entity_probe_failed");
+        expect(diagnostics[0].context).toMatchObject({ slug: "acme", uid: "cmp_acme" });
+        expect(diagnostics[0].err).toBeInstanceOf(TypeError);
+    });
+    it("with getEntity: an ordinary not-found is skipped SILENTLY", async () => {
+        const { diagnostics } = await reconcileWithProbeError(new VaultNotFoundError("company deleted"));
+        expect(diagnostics).toEqual([]);
+    });
+    it("with getEntity: a permission denial is skipped SILENTLY", async () => {
+        const { diagnostics } = await reconcileWithProbeError(new VaultPermissionDeniedError());
+        expect(diagnostics).toEqual([]);
+    });
+    it("with getEntity: a duck-typed { statusCode } rejection is treated as a lookup answer, not a bug", async () => {
+        // buildFanoutPlan classifies this same call's failures by duck-typed
+        // statusCode, so this shape is one the codebase genuinely produces.
+        const { diagnostics } = await reconcileWithProbeError({ statusCode: 404 });
+        expect(diagnostics).toEqual([]);
+    });
+    it("with getEntity: reporting is optional — omitting the sink never throws", async () => {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "acme"), { recursive: true });
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        await expect(reconcileCompanyManifest({
+            hqRoot,
+            targets: [{ uid: "cmp_acme", slug: "acme" }],
+            completedCompanySlugs: new Set(["acme"]),
+            getEntity: () => Promise.reject(new TypeError("boom")),
+        })).resolves.toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expectUntouched(manifestPath, EMPTY_MANIFEST_TEMPLATE);
+    });
+    it("with getEntity: a suspended company is rejected — the A/B twin of the plan-carried case", async () => {
+        hqRoot = makeHqRoot();
+        fs.mkdirSync(path.join(hqRoot, "companies", "susp"), { recursive: true });
+        const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
+        // Both paths must reach the SAME verdict on the same company. This is the
+        // pair that was empirically divergent before the guard was relocated.
+        expect(await reconcileCompanyManifest({
+            hqRoot,
+            targets: [{ uid: "cmp_susp", slug: "susp" }],
+            completedCompanySlugs: new Set(["susp"]),
+            getEntity: () => Promise.resolve({
+                uid: "cmp_susp",
+                slug: "susp",
+                type: "company",
+                status: "suspended",
+                name: "Suspended Corp",
+                bucketName: "hq-vault-cmp-susp",
+                createdAt: "2026-01-01T00:00:00Z",
+            }),
+        })).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expectUntouched(manifestPath, EMPTY_MANIFEST_TEMPLATE);
+        // ...and the plan-carried path agrees, with no resolver at all.
+        expect(await reconcileCompanyManifest({
+            hqRoot,
+            targets: [
+                {
+                    uid: "cmp_susp",
+                    slug: "susp",
+                    name: "Suspended Corp",
+                    bucketName: "hq-vault-cmp-susp",
+                    entityType: "company",
+                    entityStatus: "suspended",
+                },
+            ],
+            completedCompanySlugs: new Set(["susp"]),
+        })).toEqual({ written: false, added: [], updated: [], skipped: [] });
+        expectUntouched(manifestPath, EMPTY_MANIFEST_TEMPLATE);
+    });
 });
 //# sourceMappingURL=manifest-reconcile.test.js.map