@indigoai-us/hq-cloud 6.14.50 → 6.15.1

package/src/manifest-reconcile.test.ts

@@ -1,1123 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-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,
-  reconcileManifest,
-  type ManifestReconcileDiagnostic,
-} from "./manifest-reconcile.js";
-import {
-  VaultNotFoundError,
-  VaultPermissionDeniedError,
-  type EntityInfo,
-} from "./vault-client.js";
-
-let hqRoot: string | undefined;
-
-afterEach(() => {
-  if (hqRoot) {
-    fs.rmSync(hqRoot, { recursive: true, force: true });
-    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(): string {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-reconcile-"));
-  fs.mkdirSync(path.join(root, "companies"), { recursive: true });
-  return root;
-}
-
-function manifestPathFor(root: string): string {
-  return path.join(root, "companies", "manifest.yaml");
-}
-
-function writeManifest(root: string, contents: string): string {
-  const manifestPath = manifestPathFor(root);
-  fs.writeFileSync(manifestPath, contents, "utf8");
-  fs.utimesSync(manifestPath, FROZEN_MTIME, FROZEN_MTIME);
-  return manifestPath;
-}
-
-function readCompanies(manifestPath: string): Record<string, Record<string, unknown>> {
-  const parsed = yaml.load(fs.readFileSync(manifestPath, "utf8")) as {
-    companies?: Record<string, Record<string, unknown>>;
-  };
-  return parsed.companies ?? {};
-}
-
-/** Asserts the file was not touched at all — contents AND mtime. */
-function expectUntouched(manifestPath: string, before: string): void {
-  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")) as { version?: unknown }).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 as string, [
-        { 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: Array<[label: string, slug: string]> = [
-      ["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(({} as Record<string, unknown>).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 as string, [{ 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-"));
-    const companiesDir = path.join(hqRoot, "companies");
-    fs.mkdirSync(path.join(companiesDir, "acme"), { recursive: true });
-    fs.mkdirSync(path.join(companiesDir, "failed"), { recursive: true });
-    fs.mkdirSync(path.join(companiesDir, "deleted"), { recursive: true });
-
-    // This is the older manifest the personal-vault leg pulled after the
-    // cloud-company legs completed. The final merge must retain this state and
-    // add only the live, successful cloud target.
-    const manifestPath = path.join(companiesDir, "manifest.yaml");
-    fs.writeFileSync(
-      manifestPath,
-      `version: 3\nsettings:\n  keep: true\ncompanies:\n  local-only:\n    name: Local Only\n    repos:\n      - repos/local\n  preserved:\n    name: Keep Me\n    cloud_uid: cmp_preserved\n`,
-    );
-
-    const entities: Record<string, EntityInfo> = {
-      cmp_acme: {
-        uid: "cmp_acme",
-        slug: "acme",
-        type: "company",
-        status: "active",
-        name: "Acme Inc",
-        bucketName: "hq-vault-cmp-acme",
-        createdAt: "2026-01-01T00:00:00Z",
-      },
-      cmp_failed: {
-        uid: "cmp_failed",
-        slug: "failed",
-        type: "company",
-        status: "active",
-        name: "Failed Corp",
-        bucketName: "hq-vault-cmp-failed",
-        createdAt: "2026-01-01T00:00:00Z",
-      },
-      cmp_deleted: {
-        uid: "cmp_deleted",
-        slug: "deleted",
-        type: "company",
-        status: "deleted",
-        name: "Deleted Corp",
-        bucketName: "hq-vault-cmp-deleted",
-        createdAt: "2026-01-01T00:00:00Z",
-      },
-    };
-    const options = {
-      hqRoot,
-      targets: [
-        { uid: "cmp_acme", slug: "acme" },
-        { uid: "cmp_failed", slug: "failed" },
-        { uid: "cmp_deleted", slug: "deleted" },
-        { uid: "cmp_missing-directory", slug: "missing-directory" },
-        { uid: "prs_me", slug: "personal", personalMode: true },
-      ],
-      completedCompanySlugs: new Set(["acme", "deleted", "missing-directory", "personal"]),
-      getEntity: async (uid: string) => {
-        const entity = entities[uid];
-        if (!entity) throw new Error("entity not found");
-        return entity;
-      },
-    };
-
-    await reconcileCompanyManifest(options);
-    const firstWrite = fs.readFileSync(manifestPath, "utf8");
-    // 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 },
-      companies: {
-        "local-only": {
-          name: "Local Only",
-          repos: ["repos/local"],
-        },
-        preserved: {
-          name: "Keep Me",
-          cloud_uid: "cmp_preserved",
-        },
-        acme: {
-          name: "Acme Inc",
-          cloud_uid: "cmp_acme",
-          bucket_name: "hq-vault-cmp-acme",
-        },
-      },
-    });
-  });
-
-  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 (): Promise<EntityInfo> => ({
-        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 (): Promise<EntityInfo> => ({
-        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: ManifestReconcileDiagnostic[] = [];
-
-    const result = await reconcileCompanyManifest({
-      hqRoot,
-      targets: [
-        { uid: "cmp_gone", slug: "gone" },
-        { uid: "cmp_forbidden", slug: "forbidden" },
-      ],
-      completedCompanySlugs: new Set(["gone", "forbidden"]),
-      getEntity: (uid: string): Promise<EntityInfo> =>
-        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: ManifestReconcileDiagnostic[] = [];
-
-    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);
-  });
-
-  // -------------------------------------------------------------------------
-  // US-002 — entity-probe failures on the getEntity path.
-  //
-  // Every one of these SKIPS the target; that control flow is deliberate and
-  // unchanged. What differs is visibility: a routine "it's gone" answer stays
-  // quiet, while a broken resolver is reported. Without that split, a
-  // systematic resolver failure looks exactly like "joiners silently never get
-  // manifest entries" — the bug class this module exists to prevent.
-  // -------------------------------------------------------------------------
-
-  interface CapturedDiagnostic {
-    event: string;
-    message: string;
-    err: unknown;
-    context: Record<string, unknown>;
-  }
-
-  async function reconcileWithProbeError(
-    err: unknown,
-  ): Promise<{ diagnostics: CapturedDiagnostic[]; manifestPath: string }> {
-    hqRoot = makeHqRoot();
-    fs.mkdirSync(path.join(hqRoot, "companies", "acme"), { recursive: true });
-    const manifestPath = writeManifest(hqRoot, EMPTY_MANIFEST_TEMPLATE);
-
-    const diagnostics: CapturedDiagnostic[] = [];
-    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<EntityInfo> =>
-          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);
-  });
-});