@indigoai-us/hq-cloud 6.14.17 → 6.14.18

package/src/bin/sync-runner-planning.ts

@@ -29,12 +29,35 @@ export interface RunnerTarget {
   slug: string;
   name?: string;
   bucketName?: string;
+  /**
+   * Entity liveness as observed AT PLAN TIME, copied off the `entity.get`
+   * result this plan was built from. Carried so a downstream consumer can make
+   * a liveness decision without paying a second round trip.
+   *
+   * These deliberately do NOT gate SYNC. A suspended company still syncs — that
+   * is user-visible behavior and not ours to change here. They exist so the
+   * MANIFEST decision (see `manifest-reconcile.ts`) can be as strict as it was
+   * when it re-fetched the entity itself. Absent fields mean "unknown", and
+   * every consumer of them is required to fail closed.
+   */
+  entityType?: string;
+  entityStatus?: string;
   personalMode?: boolean;
   journalSlug?: string;
 }
 
+/**
+ * Why a run cannot proceed to a fanout.
+ *
+ * - `no-memberships` — the caller resolved fine but belongs to no company.
+ *   Usually a joiner whose invite is still pending acceptance.
+ * - `no-person-entity` — the caller is signed in but has no personal entity to
+ *   sync into, so even `--personal` has no target.
+ */
+export type SetupNeededReason = "no-memberships" | "no-person-entity";
+
 export type MembershipResolution =
-  | { status: "setup-needed" }
+  | { status: "setup-needed"; reason: SetupNeededReason; pendingInviteCount?: number }
   | { status: "memberships"; memberships: Pick<Membership, "companyUid">[] };
 
 export async function resolveMembershipsForRun(options: {
@@ -44,11 +67,12 @@ export async function resolveMembershipsForRun(options: {
   client: VaultClientSurface;
   claims: IdentityClaims | null;
   stderr: { write: (chunk: string) => boolean | void };
+  /** Returns how many invites were still pending after the claim attempt. */
   runClaimDance: (
     client: VaultClientSurface,
     claims: IdentityClaims,
     stderr: { write: (chunk: string) => boolean | void },
-  ) => Promise<void>;
+  ) => Promise<number>;
   listMemberships: (
     client: VaultClientSurface,
   ) => Promise<Pick<Membership, "companyUid">[]>;
@@ -58,8 +82,9 @@ export async function resolveMembershipsForRun(options: {
   }
 
   if (options.companies) {
+    let pendingInviteCount = 0;
     if (options.claims) {
-      await options.runClaimDance(
+      pendingInviteCount = await options.runClaimDance(
         options.client,
         options.claims,
         options.stderr,
@@ -68,7 +93,15 @@ export async function resolveMembershipsForRun(options: {
 
     const memberships = await options.listMemberships(options.client);
     if (memberships.length === 0) {
-      return { status: "setup-needed" };
+      // Pending invites that did NOT become memberships are the single most
+      // useful thing we can tell this user: they are not "solo", they have an
+      // invite waiting to be accepted. Reported only on the empty path, where
+      // it explains the emptiness.
+      return {
+        status: "setup-needed",
+        reason: "no-memberships",
+        ...(pendingInviteCount > 0 ? { pendingInviteCount } : {}),
+      };
     }
     return { status: "memberships", memberships };
   }
@@ -88,18 +121,31 @@ export async function buildFanoutPlan(options: {
   claims: IdentityClaims | null;
   resolveSkipPersonal: (flag: boolean) => boolean;
 }): Promise<
-  | { status: "setup-needed" }
+  | { status: "setup-needed"; reason: SetupNeededReason }
   | { status: "plan"; plan: RunnerTarget[] }
 > {
   const plan: RunnerTarget[] = [];
   for (const m of options.memberships) {
     let slug = m.companyUid;
     let name: string | undefined;
+    // Carried onto the target so downstream consumers (manifest reconciliation)
+    // can use the bucket, and judge liveness, without re-fetching the entity we
+    // already resolved here. On the degraded catch path below these stay
+    // undefined, which every consumer must read as "unknown" and reject.
+    let bucketName: string | undefined;
+    let entityType: string | undefined;
+    let entityStatus: string | undefined;
     try {
       const info = await options.client.entity.get(m.companyUid);
       if (!info) continue;
       slug = info.slug || m.companyUid;
       name = info.name;
+      bucketName = info.bucketName;
+      // Recorded, never acted on here: a suspended or unexpectedly-typed
+      // company still gets a sync leg exactly as before. Only the manifest
+      // decision consumes these.
+      entityType = info.type;
+      entityStatus = info.status;
     } catch (err) {
       if (err instanceof VaultAuthError) throw err;
       // A stale membership can outlive its company entity. Do not schedule a
@@ -117,7 +163,14 @@ export async function buildFanoutPlan(options: {
       }
       // Best-effort — keep UID as the display identifier.
     }
-    plan.push({ uid: m.companyUid, slug, ...(name ? { name } : {}) });
+    plan.push({
+      uid: m.companyUid,
+      slug,
+      ...(name ? { name } : {}),
+      ...(bucketName ? { bucketName } : {}),
+      ...(entityType ? { entityType } : {}),
+      ...(entityStatus ? { entityStatus } : {}),
+    });
   }
 
   if (
@@ -153,7 +206,7 @@ export async function buildFanoutPlan(options: {
         journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
       });
     } else if (options.personal) {
-      return { status: "setup-needed" };
+      return { status: "setup-needed", reason: "no-person-entity" };
     }
   }
 

package/src/bin/sync-runner.test.ts

@@ -52,6 +52,11 @@ import type {
 import { VaultAuthError, VaultNotFoundError } from "../vault-client.js";
 import { CognitoRefreshError } from "../cognito-auth.js";
 import type { PushEvent } from "../sync/push-event.js";
+import {
+  reconcileCompanyManifest,
+  type ManifestReconcileOptions,
+} from "../manifest-reconcile.js";
+import yaml from "js-yaml";
 
 // ---------------------------------------------------------------------------
 // Hermetic journal state — the runner now calls migratePersonalVaultJournal()
@@ -227,7 +232,9 @@ function makeDeps(overrides: Partial<RunnerDeps> = {}): TestDeps {
       embedded: false,
       pendingDirty: false,
     })),
-    reconcileManifest: vi.fn().mockResolvedValue(undefined),
+    reconcileManifest: vi
+      .fn()
+      .mockResolvedValue({ written: false, added: [], updated: [], skipped: [] }),
     ...overrides,
     stdout,
     stderr,
@@ -279,7 +286,9 @@ describe("argv parsing", () => {
     const code = await runRunner(["--companies", "--json"], deps);
     expect(code).toBe(0);
     // Empty memberships → setup-needed, not a parse error
-    expect(deps.stdout.events()).toEqual([{ type: "setup-needed" }]);
+    expect(deps.stdout.events()).toEqual([
+      { type: "setup-needed", reason: "no-memberships" },
+    ]);
   });
 });
 
@@ -618,7 +627,80 @@ describe("claim-dance", () => {
     expect(ensureSpy).not.toHaveBeenCalled();
     expect(claimSpy).not.toHaveBeenCalled();
     // No memberships, no invites — truly empty → setup-needed is correct here.
-    expect(deps.stdout.events()).toEqual([{ type: "setup-needed" }]);
+    expect(deps.stdout.events()).toEqual([
+      { type: "setup-needed", reason: "no-memberships" },
+    ]);
+  });
+
+  // The michelle@boringecom.com shape: an invite exists, the claim attempt does
+  // not convert it into a membership, and the user is told they are solo. The
+  // count is what turns "you have no team" into "you have an invite to accept".
+  it("US-004: carries pendingInviteCount when invites did not become memberships", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          pendingInvites: [{ uid: "inv_1" }, { uid: "inv_2" }] as never,
+          ensurePerson: vi
+            .fn()
+            .mockResolvedValue({ uid: "ent_person" }) as unknown as VaultClientSurface["ensureMyPersonEntity"],
+          claim: vi
+            .fn()
+            .mockResolvedValue(undefined) as unknown as VaultClientSurface["claimPendingInvitesByEmail"],
+        }),
+      getIdTokenClaims: () => claims,
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    expect(deps.stdout.events()).toEqual([
+      { type: "setup-needed", reason: "no-memberships", pendingInviteCount: 2 },
+    ]);
+  });
+
+  it("US-004: omits pendingInviteCount entirely when there were no invites", async () => {
+    const deps = makeDeps({
+      createVaultClient: () => makeVaultStub({ pendingInvites: [] }),
+      getIdTokenClaims: () => claims,
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    const [event] = deps.stdout.events();
+    expect(event).toEqual({ type: "setup-needed", reason: "no-memberships" });
+    expect("pendingInviteCount" in event).toBe(false);
+  });
+
+  it("US-004: reports claim-dance skipped as a diagnostic, not a bare stderr line", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          pendingInvites: [{ uid: "inv_1" }] as never,
+          ensurePerson: vi
+            .fn()
+            .mockRejectedValue(
+              new Error("BatchWriteItem denied"),
+            ) as unknown as VaultClientSurface["ensureMyPersonEntity"],
+        }),
+      getIdTokenClaims: () => claims,
+    });
+
+    // Non-throwing by contract: the failure never changes the exit code...
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    // ...but it is no longer invisible.
+    expect(deps.stderr.raw()).toContain("runner.claim_dance.skipped");
+  });
+
+  it("US-004: a claim-dance that cannot identify the caller still reports the pending invites", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({ pendingInvites: [{ uid: "inv_1" }] as never }),
+      // No sub/name — the claim cannot proceed, but the invites are still real.
+      getIdTokenClaims: () => ({}) as never,
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    expect(deps.stdout.events()).toEqual([
+      { type: "setup-needed", reason: "no-memberships", pendingInviteCount: 1 },
+    ]);
+    expect(deps.stderr.raw()).toContain("runner.claim_dance.skipped");
   });
 
   it("skips claim-dance entirely when no idToken claims are available", async () => {
@@ -696,7 +778,9 @@ describe("target resolution", () => {
     const deps = makeDeps();
     const code = await runRunner(["--companies"], deps);
     expect(code).toBe(0);
-    expect(deps.stdout.events()).toEqual([{ type: "setup-needed" }]);
+    expect(deps.stdout.events()).toEqual([
+      { type: "setup-needed", reason: "no-memberships" },
+    ]);
     // sync should NOT have been called — no targets
     expect(deps.sync).not.toHaveBeenCalled();
   });
@@ -1031,7 +1115,11 @@ describe("fanout-plan", () => {
       RunnerEvent,
       { type: "fanout-plan" }
     >;
-    expect(plan.companies).toEqual([{ uid: "cmp_live", slug: "live" }]);
+    // The surviving target now also carries the plan-time entity snapshot the
+    // manifest reconciler reads instead of re-fetching (US-002).
+    expect(plan.companies).toEqual([
+      { uid: "cmp_live", slug: "live", entityType: "company", entityStatus: "active" },
+    ]);
   });
 
   it("reconciles after the personal leg completes", async () => {
@@ -1066,6 +1154,7 @@ describe("fanout-plan", () => {
       }),
       reconcileManifest: vi.fn().mockImplementation(async () => {
         order.push("reconcile");
+        return { written: false, added: [], updated: [], skipped: [] };
       }),
     });
 
@@ -2723,11 +2812,9 @@ describe("personal slot fanout", () => {
     // companies/personal company journal.
     expect(lastEntry.slug).toBe("personal");
     expect(lastEntry.uid).toBe("prs_older");
-    expect((lastEntry as Record<string, unknown>).bucketName).toBe("hq-vault-prs-older");
-    expect((lastEntry as Record<string, unknown>).personalMode).toBe(true);
-    expect((lastEntry as Record<string, unknown>).journalSlug).toBe(
-      PERSONAL_VAULT_JOURNAL_SLUG,
-    );
+    expect(lastEntry.bucketName).toBe("hq-vault-prs-older");
+    expect(lastEntry.personalMode).toBe(true);
+    expect(lastEntry.journalSlug).toBe(PERSONAL_VAULT_JOURNAL_SLUG);
   });
 
   it("B: syncFn invoked with personalMode: true + reserved journalSlug for personal slot", async () => {
@@ -6581,3 +6668,336 @@ describe("US-004 — --personal for an AGENT machine identity (HARD GATE)", () =
     expect(cmp(HQ_CLOUD_VERSION, FLOOR)).toBeGreaterThanOrEqual(0);
   });
 });
+
+// ---------------------------------------------------------------------------
+// US-002 — post-fanout manifest reconciliation wiring
+//
+// The reconciler itself is unit-tested in manifest-reconcile.test.ts. These
+// tests own the SEAM: which run modes reach it, which targets cross it, and
+// what the runner does with the result it hands back.
+// ---------------------------------------------------------------------------
+
+describe("US-002 — manifest reconciliation wiring", () => {
+  const PERSON_ENTITY = {
+    uid: "prs_me",
+    slug: "me",
+    type: "person",
+    status: "active",
+    bucketName: "hq-vault-prs-me",
+    createdAt: "2026-01-01T00:00:00Z",
+  } as unknown as EntityInfo;
+
+  function noopReconcileResult() {
+    return { written: false, added: [], updated: [], skipped: [] };
+  }
+
+  /** A vault stub whose companies all resolve to `cmp_x` → slug `x`. */
+  function companiesClient(companyUids: string[]): VaultClientSurface {
+    return makeVaultStub({
+      memberships: companyUids.map((companyUid) => ({ companyUid })),
+      entityGet: (uid: string) =>
+        Promise.resolve({
+          uid,
+          slug: uid.replace(/^cmp_/, ""),
+          name: `${uid} Inc`,
+          type: "company",
+          status: "active",
+          bucketName: `bucket-${uid}`,
+          createdAt: "2026-01-01T00:00:00Z",
+        } as unknown as EntityInfo),
+      listPersons: () => Promise.resolve([PERSON_ENTITY]),
+    });
+  }
+
+  function reconcileArgs(
+    reconcile: ReturnType<typeof vi.fn>,
+  ): ManifestReconcileOptions {
+    return reconcile.mock.calls[0]![0] as ManifestReconcileOptions;
+  }
+
+  /** Diagnostics ride stderr as ndjson; pick out the manifest ones. */
+  function manifestDiagnostics(stderr: CapturingWriter): Record<string, unknown>[] {
+    return stderr
+      .lines()
+      .flatMap((line) => {
+        try {
+          return [JSON.parse(line) as Record<string, unknown>];
+        } catch {
+          return [];
+        }
+      })
+      .filter((entry) => entry.component === "manifest-reconcile");
+  }
+
+  it("AC2: an errored company is not eligible — only the completing company is", async () => {
+    const reconcile = vi.fn().mockResolvedValue(noopReconcileResult());
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_ok", "cmp_bad"]),
+      sync: vi.fn().mockImplementation(async (options: SyncOptions) => {
+        if (options.company === "cmp_bad") throw new Error("pull leg exploded");
+        return defaultSyncResult();
+      }),
+      reconcileManifest: reconcile,
+    });
+
+    await runRunner(["--companies"], deps);
+
+    expect(reconcile).toHaveBeenCalledTimes(1);
+    const args = reconcileArgs(reconcile);
+    // The completion filter is `completedCompanySlugs`; assert the EFFECTIVE
+    // eligible set, which is what actually reaches the manifest.
+    const eligible = args.targets.filter((target) =>
+      args.completedCompanySlugs.has(target.slug),
+    );
+    expect(eligible.map((target) => target.slug)).toEqual(["ok"]);
+    expect(args.completedCompanySlugs.has("bad")).toBe(false);
+  });
+
+  it("AC3: the personal target is never passed to the reconciler", async () => {
+    const reconcile = vi.fn().mockResolvedValue(noopReconcileResult());
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      reconcileManifest: reconcile,
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+
+    const args = reconcileArgs(reconcile);
+    // The personal leg definitely ran — otherwise this assertion is vacuous.
+    const plan = deps.stdout
+      .events()
+      .find((e) => e.type === "fanout-plan") as Extract<
+      RunnerEvent,
+      { type: "fanout-plan" }
+    >;
+    expect(plan.companies.map((t) => t.slug)).toContain("personal");
+
+    expect(args.targets.map((target) => target.slug)).toEqual(["acme"]);
+    expect(args.targets.some((target) => target.personalMode === true)).toBe(false);
+    expect(args.targets.some((target) => target.slug === "personal")).toBe(false);
+  });
+
+  it("AC4: --personal mode does not reconcile", async () => {
+    const reconcile = vi.fn().mockResolvedValue(noopReconcileResult());
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({ listPersons: () => Promise.resolve([PERSON_ENTITY]) }),
+      reconcileManifest: reconcile,
+    });
+
+    expect(await runRunner(["--personal"], deps)).toBe(0);
+    expect(reconcile).not.toHaveBeenCalled();
+  });
+
+  it("AC4: single-company mode (--company <slug>) does not reconcile", async () => {
+    const reconcile = vi.fn().mockResolvedValue(noopReconcileResult());
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      reconcileManifest: reconcile,
+    });
+
+    expect(await runRunner(["--company", "cmp_acme"], deps)).toBe(0);
+    expect(reconcile).not.toHaveBeenCalled();
+  });
+
+  it("AC5: company targets carry the plan-resolved bucketName, so no getEntity is passed", async () => {
+    const reconcile = vi.fn().mockResolvedValue(noopReconcileResult());
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      reconcileManifest: reconcile,
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+
+    const args = reconcileArgs(reconcile);
+    expect(args.targets[0]).toMatchObject({
+      uid: "cmp_acme",
+      slug: "acme",
+      name: "cmp_acme Inc",
+      bucketName: "bucket-cmp_acme",
+      // Liveness evidence travels with the target. Dropping the round trip
+      // must not drop the guarantee it used to provide.
+      entityType: "company",
+      entityStatus: "active",
+    });
+    // Zero extra API calls: the runner hands over no entity resolver at all.
+    expect(args.getEntity).toBeUndefined();
+  });
+
+  it("END-TO-END: a suspended company completes its sync leg but never reaches the manifest", async () => {
+    // Exercises the REAL reconciler through the runner — no stub — because the
+    // defect this guards was invisible to every stubbed assertion.
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-runner-manifest-"));
+    try {
+      fs.mkdirSync(path.join(root, "companies", "live"), { recursive: true });
+      fs.mkdirSync(path.join(root, "companies", "susp"), { recursive: true });
+      const manifestPath = path.join(root, "companies", "manifest.yaml");
+      fs.writeFileSync(manifestPath, "companies: {}\n");
+
+      const deps = makeDeps({
+        createVaultClient: () =>
+          makeVaultStub({
+            memberships: [{ companyUid: "cmp_live" }, { companyUid: "cmp_susp" }],
+            entityGet: (uid: string) =>
+              Promise.resolve({
+                uid,
+                slug: uid === "cmp_live" ? "live" : "susp",
+                type: "company",
+                // The suspended company is still a perfectly syncable target.
+                status: uid === "cmp_live" ? "active" : "suspended",
+                bucketName: `bucket-${uid}`,
+                createdAt: "2026-01-01T00:00:00Z",
+              } as unknown as EntityInfo),
+            listPersons: () => Promise.resolve([PERSON_ENTITY]),
+          }),
+        // The REAL reconciler, not the makeDeps stub — that stub is exactly
+        // what let this defect hide from every other assertion here.
+        reconcileManifest: reconcileCompanyManifest,
+      });
+
+      expect(await runRunner(["--companies", "--hq-root", root], deps)).toBe(0);
+
+      // Both companies synced (the guard must not have leaked into sync).
+      const syncedCompanies = (deps.sync as ReturnType<typeof vi.fn>).mock.calls
+        .map((call) => (call[0] as SyncOptions).company)
+        .filter(Boolean);
+      expect(syncedCompanies).toContain("cmp_live");
+      expect(syncedCompanies).toContain("cmp_susp");
+
+      // ...but only the active one earned a manifest entry.
+      const written = yaml.load(fs.readFileSync(manifestPath, "utf8")) as {
+        companies?: Record<string, unknown>;
+      };
+      expect(Object.keys(written.companies ?? {})).toEqual(["live"]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("US-003: seeds activeCompany from the completed company set", async () => {
+    const seed = vi.fn().mockReturnValue({ written: true, activeCompany: "acme" });
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      seedActiveCompany: seed,
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    expect(seed).toHaveBeenCalledTimes(1);
+    expect(seed.mock.calls[0][0]).toMatchObject({ companySlugs: ["acme"] });
+    expect(deps.stderr.raw()).toContain("active-company-seeded");
+  });
+
+  it("US-003: the personal target is never offered as an activeCompany candidate", async () => {
+    const seed = vi.fn().mockReturnValue({ written: false, skippedReason: "already-set" });
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      seedActiveCompany: seed,
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    expect(seed.mock.calls[0][0].companySlugs).not.toContain("personal");
+  });
+
+  // The two writes are independent repairs. A joiner whose manifest write fails
+  // should still get routed, and vice versa.
+  it("US-003: a failing manifest reconcile does not prevent activeCompany seeding", async () => {
+    const seed = vi.fn().mockReturnValue({ written: true, activeCompany: "acme" });
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      reconcileManifest: vi.fn().mockRejectedValue(new Error("manifest write blew up")),
+      seedActiveCompany: seed,
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    expect(deps.stderr.raw()).toContain("runner.manifest_reconcile.failed");
+    expect(seed).toHaveBeenCalledTimes(1);
+  });
+
+  it("US-003: a throwing seeder still emits all-complete and exits 0", async () => {
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      seedActiveCompany: vi.fn().mockImplementation(() => {
+        throw new Error("config write blew up");
+      }),
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    expect(deps.stdout.events().some((e) => e.type === "all-complete")).toBe(true);
+    expect(deps.stderr.raw()).toContain("runner.active_company.failed");
+  });
+
+  it("US-003: a no-op seeding is silent", async () => {
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      seedActiveCompany: vi
+        .fn()
+        .mockReturnValue({ written: false, skippedReason: "already-set" }),
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    expect(deps.stderr.raw()).not.toContain("active-company-seeded");
+  });
+
+  it("US-003: single-company mode does not seed activeCompany", async () => {
+    const seed = vi.fn();
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      seedActiveCompany: seed,
+    });
+
+    await runRunner(["--company", "acme"], deps);
+    expect(seed).not.toHaveBeenCalled();
+  });
+
+  it("AC6: a throwing reconciler still emits all-complete and exits 0", async () => {
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      reconcileManifest: vi
+        .fn()
+        .mockRejectedValue(new Error("manifest write blew up")),
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    expect(deps.stdout.events().some((e) => e.type === "all-complete")).toBe(true);
+    expect(deps.stderr.raw()).toContain("runner.manifest_reconcile.failed");
+  });
+
+  it("AC7: a write emits a manifest-reconciled diagnostic naming the slugs", async () => {
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      reconcileManifest: vi.fn().mockResolvedValue({
+        written: true,
+        added: ["acme"],
+        updated: ["beta"],
+        skipped: [],
+      }),
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+
+    const diagnostics = manifestDiagnostics(deps.stderr);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]).toMatchObject({
+      component: "manifest-reconcile",
+      event: "manifest-reconciled",
+      added: ["acme"],
+      updated: ["beta"],
+    });
+  });
+
+  it("AC7: a no-op reconciliation is completely silent (steady-state sync)", async () => {
+    const deps = makeDeps({
+      createVaultClient: () => companiesClient(["cmp_acme"]),
+      reconcileManifest: vi.fn().mockResolvedValue({
+        written: false,
+        added: [],
+        updated: [],
+        skipped: ["weird-slug"],
+      }),
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    expect(manifestDiagnostics(deps.stderr)).toEqual([]);
+    expect(deps.stderr.raw()).not.toContain("manifest-reconciled");
+  });
+});