@indigoai-us/hq-cloud 5.38.0 → 5.40.0

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

@@ -205,7 +205,7 @@ describe("argv parsing", () => {
     const deps = makeDeps();
     const code = await runRunner([], deps);
     expect(code).toBe(1);
-    expect(deps.stderr.raw()).toContain("--companies or --company");
+    expect(deps.stderr.raw()).toContain("--personal");
     expect(deps.stdout.events()).toEqual([]);
   });
 
@@ -279,15 +279,23 @@ describe("auth", () => {
     expect(deps.stdout.events()).toEqual([]);
   });
 
-  it("emits error event on stderr and returns 1 on non-auth discovery failure", async () => {
+  it("emits error event on stderr and returns 1 on non-auth discovery failure (after 3 attempts)", async () => {
+    let calls = 0;
     const deps = makeDeps({
       createVaultClient: () => ({
         ...makeVaultStub(),
-        listMyMemberships: () => Promise.reject(new Error("network down")),
+        listMyMemberships: () => {
+          calls++;
+          return Promise.reject(new Error("network down"));
+        },
       }),
     });
     const code = await runRunner(["--companies"], deps);
     expect(code).toBe(1);
+    // Memberships retry burns all 3 attempts before surfacing the error —
+    // see listMembershipsWithRetry. Auth errors short-circuit (no retry);
+    // anything else (network, 5xx) retries twice more before giving up.
+    expect(calls).toBe(3);
     // error events go to stderr, not stdout
     const events = deps.stderr.events();
     expect(events).toHaveLength(1);
@@ -300,6 +308,102 @@ describe("auth", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// memberships retry (3x with backoff, then abort)
+// ---------------------------------------------------------------------------
+//
+// `listMyMemberships()` is the single API call that drives every fanout
+// target in --companies mode. A transient network blip on this one call
+// shouldn't kill the whole sync — retry 3 times with backoff before
+// surfacing the error. Auth failures short-circuit (no retries — the
+// caller needs to re-vend, retries won't help).
+//
+// Single-company mode bypasses memberships entirely (the caller already
+// told us which company), so no retry path is needed there.
+
+describe("memberships retry", () => {
+  it("succeeds on 1st attempt with no retry", async () => {
+    let listCalls = 0;
+    const stub = makeVaultStub();
+    stub.listMyMemberships = () => {
+      listCalls++;
+      return Promise.resolve([{ companyUid: "cmp_acme" }] as Membership[]);
+    };
+    const deps = makeDeps({ createVaultClient: () => stub });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    expect(listCalls).toBe(1);
+  });
+
+  it("succeeds on 3rd attempt after 2 transient failures", async () => {
+    let listCalls = 0;
+    const stub = makeVaultStub();
+    stub.listMyMemberships = () => {
+      listCalls++;
+      if (listCalls < 3) {
+        return Promise.reject(new Error("ECONNRESET"));
+      }
+      return Promise.resolve([{ companyUid: "cmp_acme" }] as Membership[]);
+    };
+    const deps = makeDeps({ createVaultClient: () => stub });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    expect(listCalls).toBe(3);
+    // No error event should reach stderr — the retry succeeded.
+    expect(deps.stderr.events().some((e) => e.type === "error")).toBe(false);
+  });
+
+  it("exhausts 3 retries on persistent failure, then emits error event + exit 1", async () => {
+    let listCalls = 0;
+    const stub = makeVaultStub();
+    stub.listMyMemberships = () => {
+      listCalls++;
+      return Promise.reject(new Error("network down"));
+    };
+    const deps = makeDeps({ createVaultClient: () => stub });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(1);
+    expect(listCalls).toBe(3);
+    const events = deps.stderr.events();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      type: "error",
+      message: expect.stringContaining("network down"),
+      path: "(discovery)",
+    });
+  });
+
+  it("VaultAuthError short-circuits retry (no retries on auth failure)", async () => {
+    let listCalls = 0;
+    const stub = makeVaultStub();
+    stub.listMyMemberships = () => {
+      listCalls++;
+      return Promise.reject(new VaultAuthError("token expired"));
+    };
+    const deps = makeDeps({ createVaultClient: () => stub });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    // Auth failures don't retry — re-vending creds is the caller's job.
+    expect(listCalls).toBe(1);
+    expect(deps.stderr.events()).toEqual([
+      { type: "auth-error", message: "token expired" },
+    ]);
+  });
+
+  it("single-company mode bypasses listMyMemberships entirely (no retry path triggered)", async () => {
+    let listCalls = 0;
+    const stub = makeVaultStub();
+    stub.listMyMemberships = () => {
+      listCalls++;
+      return Promise.reject(new Error("should not be called"));
+    };
+    const deps = makeDeps({ createVaultClient: () => stub });
+    const code = await runRunner(["--company", "cmp_explicit"], deps);
+    expect(code).toBe(0);
+    expect(listCalls).toBe(0);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // claim-dance (first sign-in)
 // ---------------------------------------------------------------------------
@@ -478,6 +582,227 @@ describe("target resolution", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// --personal mode (personal-vault-only, skip company fanout)
+// ---------------------------------------------------------------------------
+//
+// `--personal` is mutually exclusive with `--companies` and `--company`. It
+// runs ONLY the personal-vault target — no listMyMemberships call, no
+// claim-dance, no cloud-company fanout. Designed as the replacement
+// pathway for Rust's `personal.rs::run_personal_first_push` (the menubar's
+// first-push), so the entire personal-vault walker lives in one place
+// (hq-cloud TS) and not in two duplicate engines.
+
+describe("--personal mode", () => {
+  it("argv: --personal + --companies is rejected", async () => {
+    const deps = makeDeps();
+    const code = await runRunner(["--personal", "--companies"], deps);
+    expect(code).toBe(1);
+    expect(deps.stderr.raw()).toContain("mutually exclusive");
+  });
+
+  it("argv: --personal + --company X is rejected", async () => {
+    const deps = makeDeps();
+    const code = await runRunner(["--personal", "--company", "cmp_x"], deps);
+    expect(code).toBe(1);
+    expect(deps.stderr.raw()).toContain("mutually exclusive");
+  });
+
+  it("argv: --personal + --skip-personal is rejected (contradictory)", async () => {
+    const deps = makeDeps();
+    const code = await runRunner(["--personal", "--skip-personal"], deps);
+    expect(code).toBe(1);
+    expect(deps.stderr.raw()).toContain("contradictory");
+  });
+
+  it("does NOT call listMyMemberships (skips company-discovery API entirely)", async () => {
+    const listSpy = vi.fn();
+    const deps = makeDeps({
+      createVaultClient: () => ({
+        ...makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+        listMyMemberships: listSpy as unknown as () => Promise<Membership[]>,
+      }),
+    });
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    expect(listSpy).not.toHaveBeenCalled();
+  });
+
+  it("does NOT run claim-dance (skips pending-invites + ensurePerson)", async () => {
+    const claimSpy = vi.fn();
+    const ensureSpy = vi.fn();
+    const deps = makeDeps({
+      createVaultClient: () => ({
+        ...makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+        claimPendingInvitesByEmail:
+          claimSpy as unknown as (uid: string) => Promise<void>,
+        ensureMyPersonEntity:
+          ensureSpy as unknown as VaultClientSurface["ensureMyPersonEntity"],
+      }),
+      getIdTokenClaims: () => ({
+        sub: "sub-abc",
+        email: "user@example.com",
+        name: "User Name",
+      }),
+    });
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    expect(claimSpy).not.toHaveBeenCalled();
+    expect(ensureSpy).not.toHaveBeenCalled();
+  });
+
+  it("emits fanout-plan with exactly one personal entry", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+    });
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    const plan = deps.stdout
+      .events()
+      .find((e) => e.type === "fanout-plan") as Extract<
+        RunnerEvent,
+        { type: "fanout-plan" }
+      >;
+    expect(plan).toBeDefined();
+    expect(plan.companies).toHaveLength(1);
+    expect(plan.companies[0]).toMatchObject({ slug: "personal" });
+  });
+
+  it("calls syncFn ONCE with personalMode=true (default direction=pull)", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+    });
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    expect(deps.sync).toHaveBeenCalledTimes(1);
+    const call = (deps.sync as ReturnType<typeof vi.fn>).mock
+      .calls[0][0] as SyncOptions;
+    expect(call.personalMode).toBe(true);
+  });
+
+  it("--personal --direction push calls shareFn with personalMode + computePersonalVaultPaths", async () => {
+    const shareSpy = vi.fn().mockResolvedValue({
+      filesUploaded: 0,
+      bytesUploaded: 0,
+      filesSkipped: 0,
+      filesDeleted: 0,
+      conflictPaths: [],
+      aborted: false,
+    });
+    const deps = makeDeps({
+      share: shareSpy as unknown as RunnerDeps["share"],
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+    });
+    const code = await runRunner(["--personal", "--direction", "push"], deps);
+    expect(code).toBe(0);
+    expect(shareSpy).toHaveBeenCalledTimes(1);
+    const opts = shareSpy.mock.calls[0][0];
+    expect(opts.personalMode).toBe(true);
+    // paths come from computePersonalVaultPaths — non-empty array of
+    // absolute hqRoot-anchored paths. Don't pin the exact contents
+    // (depends on hqRoot's local layout); just confirm the shape.
+    expect(Array.isArray(opts.paths)).toBe(true);
+  });
+
+  it("no person entity → emits setup-needed event, exit 0 (same shape as --companies)", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () => Promise.resolve([]),
+        }),
+    });
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    expect(
+      deps.stdout.events().some((e) => e.type === "setup-needed"),
+    ).toBe(true);
+    expect(deps.sync).not.toHaveBeenCalled();
+  });
+
+  it("--personal honors --direction both (calls both shareFn and syncFn)", async () => {
+    const shareSpy = vi.fn().mockResolvedValue({
+      filesUploaded: 0,
+      bytesUploaded: 0,
+      filesSkipped: 0,
+      filesDeleted: 0,
+      conflictPaths: [],
+      aborted: false,
+    });
+    const deps = makeDeps({
+      share: shareSpy as unknown as RunnerDeps["share"],
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+    });
+    const code = await runRunner(["--personal", "--direction", "both"], deps);
+    expect(code).toBe(0);
+    expect(shareSpy).toHaveBeenCalledTimes(1);
+    expect(deps.sync).toHaveBeenCalledTimes(1);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // fanout-plan
 // ---------------------------------------------------------------------------

package/src/bin/sync-runner.ts

@@ -340,6 +340,46 @@ export interface VaultClientSurface {
   };
 }
 
+/**
+ * Backoff schedule (in ms) between attempts 2 and 3 of
+ * `listMembershipsWithRetry`. Short on purpose — memberships is a single
+ * API call gating the whole runner, and a transient blip (DNS hiccup,
+ * idle ALB connection reset) usually clears in <50ms. If the network is
+ * genuinely down, three attempts in <200ms total fail fast enough that
+ * the tray can show its error banner before the user notices a delay.
+ */
+const MEMBERSHIPS_RETRY_BACKOFFS_MS: readonly number[] = [50, 100];
+
+/**
+ * Call `listMyMemberships()` with up to 3 attempts and a small linear
+ * backoff between them. The single network call that drives every cloud
+ * company target plus the personal-vault slot — a one-off network blip
+ * shouldn't kill the whole sync run.
+ *
+ * Auth failures (VaultAuthError) bypass retry entirely: re-vending creds
+ * is the caller's job, not retryable in-process. Re-throwing immediately
+ * preserves the existing auth-error event semantics in the outer
+ * try/catch.
+ */
+async function listMembershipsWithRetry(
+  client: VaultClientSurface,
+): Promise<Membership[]> {
+  let lastErr: unknown;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (attempt > 0) {
+      const delayMs = MEMBERSHIPS_RETRY_BACKOFFS_MS[attempt - 1] ?? 100;
+      await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
+    }
+    try {
+      return await client.listMyMemberships();
+    } catch (err) {
+      if (err instanceof VaultAuthError) throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
 /** Minimal shape of the claims we read off the Cognito idToken. */
 interface IdTokenClaims {
   sub?: string;
@@ -461,6 +501,16 @@ async function runClaimDance(
 interface ParsedArgs {
   companies: boolean;
   company?: string;
+  /**
+   * Personal-vault-only mode. Mutually exclusive with `--companies` and
+   * `--company`. Skips `listMyMemberships` (and therefore the claim-dance);
+   * builds a fanout plan containing ONLY the personal target. Designed as
+   * the runner-side entry point that replaces Rust's
+   * `personal.rs::run_personal_first_push` first-push walker — so the
+   * personal-vault scope (`computePersonalVaultPaths`) lives in exactly
+   * one place (this TS engine) and not duplicated across engines.
+   */
+  personal: boolean;
   onConflict: ConflictStrategy;
   hqRoot: string;
   direction: Direction;
@@ -489,6 +539,7 @@ interface ParsedArgs {
 function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let companies = false;
   let company: string | undefined;
+  let personal = false;
   let onConflict: ConflictStrategy = "abort";
   let hqRoot = DEFAULT_HQ_ROOT;
   let direction: Direction = "pull";
@@ -507,6 +558,14 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
         company = argv[++i];
         if (!company) return { error: "--company requires a value" };
         break;
+      case "--personal":
+        // Personal-vault-only mode. Skips listMyMemberships + claim-dance
+        // entirely; builds a fanout plan containing only the personal target.
+        // Replaces Rust's personal.rs::run_personal_first_push walker —
+        // the personal-vault scope (computePersonalVaultPaths) is owned
+        // by this engine, not duplicated across Rust + TS.
+        personal = true;
+        break;
       case "--on-conflict": {
         const val = argv[++i];
         if (val !== "abort" && val !== "overwrite" && val !== "keep") {
@@ -569,8 +628,18 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   if (companies && company) {
     return { error: "Pass --companies OR --company <slug>, not both" };
   }
-  if (!companies && !company) {
-    return { error: "Pass --companies or --company <slug>" };
+  if (personal && (companies || company)) {
+    return {
+      error: "--personal is mutually exclusive with --companies / --company",
+    };
+  }
+  if (personal && skipPersonal) {
+    return {
+      error: "--personal and --skip-personal are contradictory",
+    };
+  }
+  if (!companies && !company && !personal) {
+    return { error: "Pass --companies, --company <slug>, or --personal" };
   }
   if (pollRemoteMs !== undefined && !watch) {
     return { error: "--poll-remote-ms requires --watch" };
@@ -582,6 +651,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   return {
     companies,
     company,
+    personal,
     onConflict,
     hqRoot,
     direction,
@@ -734,7 +804,15 @@ export async function runRunner(
   // ---- resolve targets --------------------------------------------------
   let memberships: Pick<Membership, "companyUid">[];
   try {
-    if (parsed.companies) {
+    if (parsed.personal) {
+      // Personal-vault-only mode: skip listMyMemberships entirely (and
+      // therefore the claim-dance). The fanout plan is built solely from
+      // the person-entity lookup below — no cloud-company targets, no
+      // /membership/me round-trip. setup-needed is deferred to the
+      // person-entity check (firing only when the personal entity is
+      // also absent, not when memberships are empty by design).
+      memberships = [];
+    } else if (parsed.companies) {
       // Before giving up on memberships, run the claim-dance: new users signed
       // in via the tray may have email-keyed invites waiting for them. Without
       // this, an invited user would see "setup-needed" on every tray click.
@@ -742,7 +820,7 @@ export async function runRunner(
         await runClaimDance(client, claims, stderr);
       }
 
-      memberships = await client.listMyMemberships();
+      memberships = await listMembershipsWithRetry(client);
       if (memberships.length === 0) {
         // Truly empty — still a valid state (no memberships = nothing to
         // sync). The tray will show a friendly "create your first company"
@@ -800,7 +878,10 @@ export async function runRunner(
     plan.push({ uid: m.companyUid, slug, ...(name ? { name } : {}) });
   }
 
-  if (parsed.companies && !resolveSkipPersonal(parsed.skipPersonal)) {
+  if (
+    (parsed.companies || parsed.personal) &&
+    !resolveSkipPersonal(parsed.skipPersonal)
+  ) {
     // Personal-target fanout slot. Skipped entirely when --skip-personal
     // (or HQ_SYNC_SKIP_PERSONAL=1) is set — see resolveSkipPersonal doc for
     // the rationale (menubar opt-out for users who only want company sync).
@@ -809,6 +890,9 @@ export async function runRunner(
     // workspaces row, status surfaces) should already tolerate that
     // shape since pre-5.25 fanout often had it (a user with no person
     // entity yet, or before the canonical-person-entity machinery landed).
+    //
+    // `--personal` mode reaches this block with an empty `plan` and
+    // empty `memberships`; only the personal target gets added below.
     const persons = await client.entity.listByType("person");
     const pick = pickCanonicalPersonEntity(persons);
     if (pick?.bucketName) {
@@ -824,6 +908,14 @@ export async function runRunner(
         // root-cause writeup.
         journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
       });
+    } else if (parsed.personal) {
+      // --personal mode with no canonical personal entity → setup-needed.
+      // (In --companies mode this state is silent — companies still sync
+      // and the missing personal target just shows an empty workspaces row.
+      // In --personal mode it's the ONLY signal, so it gets surfaced as
+      // setup-needed with the same shape as the empty-memberships case.)
+      emit({ type: "setup-needed" });
+      return 0;
     }
   }
 

package/src/personal-vault.test.ts

@@ -228,4 +228,95 @@ describe("personal-vault helpers", () => {
     fs.rmSync(hqRoot, { recursive: true });
     expect(computePersonalVaultPaths(hqRoot, { includeLocalCompanies: true })).toEqual([]);
   });
+
+  // ── companies/manifest.yaml inclusion ─────────────────────────────────
+  //
+  // The manifest is the routing source-of-truth (which slugs exist, which
+  // are cloud-backed, what their company UIDs are). The vault needs a
+  // single canonical copy: without it, a fresh machine joining the
+  // personal vault has no way to enumerate which non-cloud companies it
+  // expects to pull. Special-cased because companies/ itself is in
+  // PERSONAL_VAULT_EXCLUDED_TOP_LEVEL.
+  it("manifest: includes companies/manifest.yaml when present (default opts)", () => {
+    fs.mkdirSync(path.join(hqRoot, "companies"));
+    fs.writeFileSync(
+      path.join(hqRoot, "companies", "manifest.yaml"),
+      "companies:\n  foo: {}\n",
+    );
+    fs.mkdirSync(path.join(hqRoot, ".claude"));
+
+    const out = rel(computePersonalVaultPaths(hqRoot));
+    expect(out).toContain(path.join("companies", "manifest.yaml"));
+    expect(out).toContain(".claude");
+  });
+
+  it("manifest: included even when includeLocalCompanies=false (manifest is unconditional)", () => {
+    fs.mkdirSync(path.join(hqRoot, "companies"));
+    fs.writeFileSync(
+      path.join(hqRoot, "companies", "manifest.yaml"),
+      "companies: {}\n",
+    );
+
+    const out = rel(
+      computePersonalVaultPaths(hqRoot, { includeLocalCompanies: false }),
+    );
+    expect(out).toContain(path.join("companies", "manifest.yaml"));
+  });
+
+  it("manifest: absent file is not included (no crash, no phantom entry)", () => {
+    fs.mkdirSync(path.join(hqRoot, "companies"));
+    // No manifest.yaml written.
+
+    const out = rel(computePersonalVaultPaths(hqRoot));
+    expect(out).not.toContain(path.join("companies", "manifest.yaml"));
+  });
+
+  it("manifest: missing companies/ directory entirely is not an error", () => {
+    // Fresh install or atypical layout: no companies/ dir at all.
+    fs.mkdirSync(path.join(hqRoot, ".claude"));
+    expect(() => computePersonalVaultPaths(hqRoot)).not.toThrow();
+    const out = rel(computePersonalVaultPaths(hqRoot));
+    expect(out).toContain(".claude");
+    expect(out).not.toContain(path.join("companies", "manifest.yaml"));
+  });
+
+  it("manifest: ONLY manifest.yaml is special-cased — other companies/ root files stay excluded", () => {
+    // Anti-test: only manifest.yaml gets the bypass. A stray README.md at
+    // companies/ root or a directory called `_template` must still be
+    // filtered (the latter by company-eligibility, the former silently).
+    fs.mkdirSync(path.join(hqRoot, "companies"));
+    fs.writeFileSync(
+      path.join(hqRoot, "companies", "manifest.yaml"),
+      "companies: {}\n",
+    );
+    fs.writeFileSync(
+      path.join(hqRoot, "companies", "README.md"),
+      "# companies tree",
+    );
+
+    const out = rel(computePersonalVaultPaths(hqRoot));
+    expect(out).toContain(path.join("companies", "manifest.yaml"));
+    expect(out).not.toContain(path.join("companies", "README.md"));
+  });
+
+  it("manifest: composes with includeLocalCompanies=true + local company subdirs", () => {
+    fs.mkdirSync(path.join(hqRoot, "companies"));
+    fs.writeFileSync(
+      path.join(hqRoot, "companies", "manifest.yaml"),
+      "companies:\n  foo: {cloud_uid: null}\n  team-acme: {cloud_uid: cmp_01XYZ}\n",
+    );
+    writeCompany("foo", "cloud: false\n");
+    writeCompany("team-acme", "cloud: true\n");
+
+    const out = rel(
+      computePersonalVaultPaths(hqRoot, {
+        includeLocalCompanies: true,
+        teamSyncedSlugs: new Set(["team-acme"]),
+      }),
+    );
+    // Manifest + non-cloud subdir, NOT team-acme.
+    expect(out).toContain(path.join("companies", "manifest.yaml"));
+    expect(out).toContain(path.join("companies", "foo"));
+    expect(out).not.toContain(path.join("companies", "team-acme"));
+  });
 });

package/src/personal-vault.ts

@@ -105,10 +105,25 @@ export function computePersonalVaultPaths(
   const topLevel = entries
     .filter((name) => !PERSONAL_VAULT_EXCLUDED_TOP_LEVEL.includes(name))
     .map((name) => path.join(hqRoot, name));
+  // companies/manifest.yaml is the routing source-of-truth (which slugs
+  // exist, which are cloud-backed, what their UIDs are). It must travel
+  // with every machine's personal vault so a fresh install can enumerate
+  // expected non-cloud companies before its first pull. Special-cased
+  // because the parent `companies/` is in PERSONAL_VAULT_EXCLUDED_TOP_LEVEL
+  // (we never enumerate the whole companies tree wholesale).
+  const manifest: string[] = [];
+  const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+  try {
+    if (fs.statSync(manifestPath).isFile()) {
+      manifest.push(manifestPath);
+    }
+  } catch {
+    // Missing or unreadable — silently omit. Callers tolerate empty arrays.
+  }
   const companySubdirs = opts.includeLocalCompanies === true
     ? computePersonalCompanySubdirs(hqRoot, opts.teamSyncedSlugs)
     : [];
-  return [...topLevel, ...companySubdirs];
+  return [...topLevel, ...manifest, ...companySubdirs];
 }
 
 /**