@indigoai-us/hq-cloud 5.1.12 → 5.2.0

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

@@ -85,6 +85,7 @@ function makeVaultStub(
   opts: {
     memberships?: Array<Pick<Membership, "companyUid">>;
     entityGet?: (uid: string) => Promise<EntityInfo>;
+    listPersons?: () => Promise<EntityInfo[]>;
     pendingInvites?: Array<Record<string, unknown>>;
     ensurePerson?: (hints: {
       ownerSub: string;
@@ -121,6 +122,9 @@ function makeVaultStub(
             bucketName: `bucket-${uid}`,
             status: "active",
           } as unknown as EntityInfo)),
+      listByType:
+        opts.listPersons ??
+        (() => Promise.resolve([])),
     },
   };
 }
@@ -1050,6 +1054,110 @@ describe("--direction", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Personal slot fanout (A/B/C)
+// ---------------------------------------------------------------------------
+
+describe("personal slot fanout", () => {
+  const olderPerson: EntityInfo = {
+    uid: "prs_older",
+    slug: "older-person",
+    type: "person",
+    status: "active",
+    createdAt: "2026-01-01T00:00:00Z",
+    bucketName: "hq-vault-prs-older",
+  } as unknown as EntityInfo;
+
+  const newerPerson: EntityInfo = {
+    uid: "prs_newer",
+    slug: "newer-person",
+    type: "person",
+    status: "active",
+    createdAt: "2026-06-01T00:00:00Z",
+    bucketName: "hq-vault-prs-newer",
+  } as unknown as EntityInfo;
+
+  it("A: fanout-plan ends with personal slot using canonical-sort-selected person (older createdAt wins)", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          memberships: [{ companyUid: "cmp_a" }],
+          entityGet: (uid: string) =>
+            Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
+          // Return persons in reversed order (newer first) to test canonical sort
+          listPersons: () => Promise.resolve([newerPerson, olderPerson]),
+        }),
+    });
+
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+
+    const planEvent = deps.stdout
+      .events()
+      .find((e) => e.type === "fanout-plan") as Extract<RunnerEvent, { type: "fanout-plan" }>;
+    expect(planEvent).toBeDefined();
+
+    const lastEntry = planEvent.companies[planEvent.companies.length - 1];
+    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");
+  });
+
+  it("B: syncFn invoked with personalMode: true + journalSlug: 'personal' for personal slot", async () => {
+    const syncSpy = vi.fn().mockResolvedValue(defaultSyncResult());
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          memberships: [{ companyUid: "cmp_a" }],
+          entityGet: (uid: string) =>
+            Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
+          listPersons: () => Promise.resolve([newerPerson, olderPerson]),
+        }),
+      sync: syncSpy,
+    });
+
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+
+    const personalCall = (syncSpy.mock.calls as Array<[SyncOptions]>).find(
+      (c) => c[0].company?.startsWith("prs_"),
+    );
+    expect(personalCall).toBeDefined();
+    const personalArgs = personalCall![0];
+    expect(personalArgs.personalMode).toBe(true);
+    expect(personalArgs.journalSlug).toBe("personal");
+  });
+
+  it("C: company slots' syncFn args do NOT contain personalMode or journalSlug", async () => {
+    const syncSpy = vi.fn().mockResolvedValue(defaultSyncResult());
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          memberships: [{ companyUid: "cmp_a" }],
+          entityGet: (uid: string) =>
+            Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
+          listPersons: () => Promise.resolve([olderPerson]),
+        }),
+      sync: syncSpy,
+    });
+
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+
+    const companyCalls = (syncSpy.mock.calls as Array<[SyncOptions]>).filter(
+      (c) => c[0].company?.startsWith("cmp_"),
+    );
+    expect(companyCalls.length).toBeGreaterThan(0);
+    for (const [args] of companyCalls) {
+      const keys = Object.keys(args);
+      expect(keys).not.toContain("personalMode");
+      expect(keys).not.toContain("journalSlug");
+    }
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Re-initialize for each test (mock state hygiene)
 // ---------------------------------------------------------------------------

package/src/bin/sync-runner.ts

@@ -48,6 +48,7 @@ import {
   type EntityInfo,
   type PendingInviteByEmail,
 } from "../index.js";
+import { pickCanonicalPersonEntity } from "../vault-client.js";
 import { sync as defaultSync } from "../cli/sync.js";
 import type {
   SyncOptions,
@@ -155,6 +156,7 @@ export interface VaultClientSurface {
   }) => Promise<EntityInfo>;
   entity: {
     get: (uid: string) => Promise<EntityInfo>;
+    listByType: (type: string) => Promise<EntityInfo[]>;
   };
 }
 
@@ -430,7 +432,14 @@ export async function runRunner(
   // The menubar wants "Syncing indigo" in its UI, not the raw cmp_* ULID.
   // If the entity fetch fails for some row (entity deleted, scoping issue),
   // degrade to using the UID as the slug rather than aborting the run.
-  const plan: Array<{ uid: string; slug: string; name?: string }> = [];
+  const plan: Array<{
+    uid: string;
+    slug: string;
+    name?: string;
+    bucketName?: string;
+    personalMode?: boolean;
+    journalSlug?: string;
+  }> = [];
   for (const m of memberships) {
     let slug = m.companyUid;
     let name: string | undefined;
@@ -443,6 +452,21 @@ export async function runRunner(
     }
     plan.push({ uid: m.companyUid, slug, ...(name ? { name } : {}) });
   }
+
+  if (parsed.companies) {
+    const persons = await client.entity.listByType("person");
+    const pick = pickCanonicalPersonEntity(persons);
+    if (pick?.bucketName) {
+      plan.push({
+        slug: "personal",
+        uid: pick.uid,
+        bucketName: pick.bucketName,
+        personalMode: true,
+        journalSlug: "personal",
+      });
+    }
+  }
+
   emit({ type: "fanout-plan", companies: plan });
 
   // ---- fanout -----------------------------------------------------------
@@ -519,6 +543,8 @@ export async function runRunner(
           vaultConfig,
           hqRoot: parsed.hqRoot,
           onConflict: parsed.onConflict,
+          ...(target.personalMode !== undefined ? { personalMode: target.personalMode } : {}),
+          ...(target.journalSlug !== undefined ? { journalSlug: target.journalSlug } : {}),
           onEvent: tagAndEmit,
         });
       }

package/src/cli/sync.test.ts

@@ -34,6 +34,7 @@ vi.mock("../s3.js", async () => {
 });
 
 import { sync } from "./sync.js";
+import * as s3Module from "../s3.js";
 
 const mockConfig: VaultServiceConfig = {
   apiUrl: "https://vault-api.test",
@@ -210,6 +211,48 @@ describe("sync", () => {
     expect(result.aborted).toBe(true);
   });
 
+  it("journalSlug: 'personal' routes journal I/O to sync-journal.personal.json", async () => {
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      journalSlug: "personal",
+    });
+
+    expect(result.filesDownloaded).toBe(2);
+    // Journal written to personal slug, not ctx.slug ("acme")
+    const personalJournalPath = path.join(stateDir, "sync-journal.personal.json");
+    expect(fs.existsSync(personalJournalPath)).toBe(true);
+    // The acme journal must NOT have been written
+    expect(fs.existsSync(journalPath)).toBe(false);
+  });
+
+  it("personalMode: true skips companies/* keys and downloads root keys to hqRoot", async () => {
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "companies/foo/bar.md", size: 50, lastModified: new Date(), etag: '"xyz789"' },
+      { key: "docs/readme.md",       size: 30, lastModified: new Date(), etag: '"abc000"' },
+    ]);
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+    });
+
+    // Exact counts (regression-tight)
+    expect(result.filesSkipped).toBe(1);
+    expect(result.filesDownloaded).toBe(1);
+
+    // companies/* must NOT land anywhere
+    expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "companies", "foo", "bar.md"))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "foo", "bar.md"))).toBe(false);
+
+    // docs/readme.md MUST land at <hqRoot>/docs/readme.md (NOT <hqRoot>/companies/<slug>/docs/readme.md)
+    expect(fs.existsSync(path.join(tmpDir, "docs", "readme.md"))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "docs", "readme.md"))).toBe(false);
+  });
+
   it("overwrites local on --on-conflict overwrite", async () => {
     const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
     fs.mkdirSync(companyDocs, { recursive: true });

package/src/cli/sync.ts

@@ -46,6 +46,19 @@ export interface SyncOptions {
    * default human logger is used. See `SyncProgressEvent`.
    */
   onEvent?: (event: SyncProgressEvent) => void;
+  /**
+   * When true, the caller is syncing against the caller's person-entity
+   * bucket. Pulled keys whose path starts with `companies/` are dropped
+   * (belt-and-braces — the person bucket should never contain those,
+   * but the runner must not write them into the user's company folders).
+   */
+  personalMode?: boolean;
+  /**
+   * Override for the per-slug journal file name. Defaults to `ctx.slug`.
+   * sync-runner passes `journalSlug: "personal"` for the personal slot so
+   * TS runner and Rust first-push share idempotency state.
+   */
+  journalSlug?: string;
 }
 
 export interface SyncResult {
@@ -78,9 +91,16 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   // companies into the same hqRoot doesn't cross-clobber files with overlapping
   // S3 keys (e.g. every company has a .hq/manifest.json). Remote keys stay
   // company-relative; the prefix lives only on disk.
-  const companyRoot = path.join(hqRoot, "companies", ctx.slug);
+  // In personalMode the journal slug + S3 keys are person-relative (e.g. "docs/foo.md");
+  // the local target is `hqRoot` directly, NOT `<hqRoot>/companies/<personSlug>/`. This
+  // keeps round-trip parity with the Rust personal first-push (Step 7) which sources
+  // `<hqRoot>/docs/foo.md`.
+  const companyRoot = options.personalMode === true
+    ? hqRoot
+    : path.join(hqRoot, "companies", ctx.slug);
   const shouldSync = createIgnoreFilter(hqRoot);
-  const journal = readJournal(ctx.slug);
+  const journalSlug = options.journalSlug ?? ctx.slug;
+  const journal = readJournal(journalSlug);
 
   let filesDownloaded = 0;
   let bytesDownloaded = 0;
@@ -93,6 +113,11 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   for (const remoteFile of remoteFiles) {
     const localPath = path.join(companyRoot, remoteFile.key);
 
+    if (options.personalMode === true && remoteFile.key.startsWith("companies/")) {
+      filesSkipped++;
+      continue;
+    }
+
     // Apply ignore rules
     if (!shouldSync(localPath)) {
       filesSkipped++;
@@ -126,7 +151,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
         );
 
         if (resolution === "abort") {
-          writeJournal(ctx.slug, journal);
+          writeJournal(journalSlug, journal);
           return { filesDownloaded, bytesDownloaded, filesSkipped, conflicts, aborted: true };
         }
         if (resolution === "keep" || resolution === "skip") {
@@ -181,7 +206,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     }
   }
 
-  writeJournal(ctx.slug, journal);
+  writeJournal(journalSlug, journal);
 
   return { filesDownloaded, bytesDownloaded, filesSkipped, conflicts, aborted: false };
 }

package/src/context.test.ts

@@ -162,11 +162,114 @@ describe("resolveEntityContext", () => {
     setupFetchMock({ vendStatus: 403 });
 
     await expect(resolveEntityContext("acme", mockConfig)).rejects.toThrow(
-      /STS vend failed/,
+      /STS.*vend.*failed/,
     );
   });
 });
 
+describe("routing by UID prefix and vend-self dispatch", () => {
+  beforeEach(() => {
+    clearContextCache();
+    vi.restoreAllMocks();
+  });
+
+  it("prs_* UID: entity resolved via /entity/{uid} and credentials via /sts/vend-self", async () => {
+    const prsEntity = {
+      uid: "prs_01PERSON",
+      slug: "test-person",
+      bucketName: "hq-vault-prs-01person",
+      status: "active",
+    };
+    const calls: string[] = [];
+    vi.stubGlobal("fetch", vi.fn().mockImplementation(async (url: string) => {
+      const u = String(url);
+      calls.push(u);
+      if (u.includes("/entity/prs_")) {
+        return { ok: true, status: 200, json: async () => ({ entity: prsEntity }), text: async () => "" };
+      }
+      if (u.includes("/sts/vend-self")) {
+        return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+      }
+      return { ok: false, status: 404, text: async () => "Not found" };
+    }));
+
+    await resolveEntityContext("prs_01PERSON", mockConfig);
+
+    expect(calls.some((u) => u.includes("/entity/prs_01PERSON"))).toBe(true);
+    const vendCalls = calls.filter((u) => u.includes("/sts/vend"));
+    expect(vendCalls).toHaveLength(1);
+    expect(vendCalls[0]).toContain("/sts/vend-self");
+  });
+
+  it("foo_bar slug: entity resolved via /entity/by-slug/company/foo_bar and credentials via /sts/vend", async () => {
+    const calls: string[] = [];
+    vi.stubGlobal("fetch", vi.fn().mockImplementation(async (url: string) => {
+      const u = String(url);
+      calls.push(u);
+      if (u.includes("/entity/by-slug/")) {
+        return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+      }
+      if (u.includes("/sts/vend")) {
+        return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+      }
+      return { ok: false, status: 404, text: async () => "Not found" };
+    }));
+
+    await resolveEntityContext("foo_bar", mockConfig);
+
+    expect(calls.some((u) => u.includes("/entity/by-slug/company/foo_bar"))).toBe(true);
+    const vendCalls = calls.filter((u) => u.includes("/sts/vend"));
+    expect(vendCalls).toHaveLength(1);
+    expect(vendCalls[0]).not.toContain("/sts/vend-self");
+    expect(vendCalls[0]).toContain("/sts/vend");
+  });
+
+  it("team_alpha slug: entity resolved via /entity/by-slug/company/team_alpha and credentials via /sts/vend", async () => {
+    const calls: string[] = [];
+    vi.stubGlobal("fetch", vi.fn().mockImplementation(async (url: string) => {
+      const u = String(url);
+      calls.push(u);
+      if (u.includes("/entity/by-slug/")) {
+        return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+      }
+      if (u.includes("/sts/vend")) {
+        return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+      }
+      return { ok: false, status: 404, text: async () => "Not found" };
+    }));
+
+    await resolveEntityContext("team_alpha", mockConfig);
+
+    expect(calls.some((u) => u.includes("/entity/by-slug/company/team_alpha"))).toBe(true);
+    const vendCalls = calls.filter((u) => u.includes("/sts/vend"));
+    expect(vendCalls).toHaveLength(1);
+    expect(vendCalls[0]).not.toContain("/sts/vend-self");
+  });
+
+  it("cmp_* UID: entity resolved via /entity/{uid} and credentials via /sts/vend", async () => {
+    const calls: string[] = [];
+    vi.stubGlobal("fetch", vi.fn().mockImplementation(async (url: string) => {
+      const u = String(url);
+      calls.push(u);
+      if (u.includes("/entity/cmp_")) {
+        return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+      }
+      if (u.includes("/sts/vend")) {
+        return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+      }
+      return { ok: false, status: 404, text: async () => "Not found" };
+    }));
+
+    await resolveEntityContext("cmp_01ABCDEF", mockConfig);
+
+    expect(calls.some((u) => u.includes("/entity/cmp_01ABCDEF"))).toBe(true);
+    const vendCalls = calls.filter((u) => u.includes("/sts/vend"));
+    expect(vendCalls).toHaveLength(1);
+    expect(vendCalls[0]).not.toContain("/sts/vend-self");
+    expect(vendCalls[0]).toContain("/sts/vend");
+  });
+});
+
 describe("refreshEntityContext", () => {
   beforeEach(() => {
     clearContextCache();

package/src/context.ts

@@ -17,6 +17,13 @@ const DEFAULT_SESSION_DURATION_SECONDS = 900;
 /** Cached contexts keyed by entity UID. */
 const contextCache = new Map<string, EntityContext>();
 
+/**
+ * Closed-set of recognised entity-UID prefixes. Adding a new entity type
+ * means appending one entry here AND extending the dispatch in
+ * `resolveEntityContext` (cmp_ → /sts/vend, prs_ → /sts/vend-self).
+ */
+export const KNOWN_UID_PREFIXES = ["cmp_", "prs_"] as const;
+
 /**
  * Look up an entity by slug or UID via vault-service, then vend STS-scoped
  * credentials for that entity. Returns an EntityContext ready for S3 ops.
@@ -34,9 +41,15 @@ export async function resolveEntityContext(
     return cached;
   }
 
-  // Step 1: Resolve entity — if it looks like a UID (cmp_*), fetch directly;
-  // otherwise look up by slug
-  const entity = companyUidOrSlug.startsWith("cmp_")
+  // Step 1: Resolve entity — if it looks like a known UID prefix, fetch directly;
+  // otherwise look up by slug. Explicit enumeration avoids over-matching slugs
+  // like foo_bar or team_alpha that happen to look like UIDs.
+  const looksLikeUid = KNOWN_UID_PREFIXES.some((p) =>
+    companyUidOrSlug.startsWith(p),
+  );
+  const looksLikePerson = companyUidOrSlug.startsWith("prs_");
+
+  const entity = looksLikeUid
     ? await fetchEntity(companyUidOrSlug, config)
     : await fetchEntityBySlug("company", companyUidOrSlug, config);
 
@@ -47,8 +60,13 @@ export async function resolveEntityContext(
     );
   }
 
-  // Step 2: Vend STS-scoped credentials
-  const vendResult = await vendCredentials(entity.uid, config);
+  // Step 2: Dispatch credential vending by UID prefix.
+  //   cmp_* → POST /sts/vend      (company path; membership-gated)
+  //   prs_* → POST /sts/vend-self (person path; self-ownership-gated)
+  //   slug  → POST /sts/vend      (legacy slug path is company-only)
+  const vendResult = looksLikePerson
+    ? await vendSelfCredentials(entity.uid, config)
+    : await vendCredentials(entity.uid, config);
 
   const ctx: EntityContext = {
     uid: entity.uid,
@@ -153,26 +171,38 @@ async function fetchEntityBySlug(
   return data.entity;
 }
 
-async function vendCredentials(
-  companyUid: string,
+async function postVend(
+  route: string,
+  body: Record<string, unknown>,
   config: VaultServiceConfig,
 ): Promise<VendResponse> {
-  const res = await fetch(`${config.apiUrl}/sts/vend`, {
+  const res = await fetch(`${config.apiUrl}${route}`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${config.authToken}`,
     },
-    body: JSON.stringify({
-      companyUid,
-      durationSeconds: DEFAULT_SESSION_DURATION_SECONDS,
-    }),
+    body: JSON.stringify({ ...body, durationSeconds: DEFAULT_SESSION_DURATION_SECONDS }),
   });
   if (!res.ok) {
-    const body = await res.text();
-    throw new Error(
-      `STS vend failed for ${companyUid}: ${res.status} ${body}`,
-    );
+    const text = await res.text();
+    throw new Error(`STS ${route} failed: ${res.status} ${text}`);
   }
   return (await res.json()) as VendResponse;
 }
+
+async function vendCredentials(
+  companyUid: string,
+  config: VaultServiceConfig,
+): Promise<VendResponse> {
+  return postVend("/sts/vend", { companyUid }, config);
+}
+
+async function vendSelfCredentials(
+  personUid: string,
+  config: VaultServiceConfig,
+): Promise<VendResponse> {
+  // Use `+` concat at the literal so guard 5 (grep "/sts/vend-self") still finds it
+  const route = "/sts/vend-self";
+  return postVend(route, { personUid }, config);
+}

package/src/ignore.ts

@@ -20,7 +20,7 @@ import ignore from "ignore";
 
 // Patterns that must never sync regardless of project type.
 // Grouped by ecosystem so new stacks are easy to add.
-const DEFAULT_IGNORES = [
+export const DEFAULT_IGNORES = [
   // VCS + OS
   ".git/",
   ".git",

package/src/vault-client.test.ts

@@ -12,6 +12,8 @@ import {
   VaultNotFoundError,
   VaultConflictError,
   VaultClientError,
+  pickCanonicalPersonEntity,
+  type EntityInfo,
 } from "./vault-client.js";
 
 // ---------------------------------------------------------------------------
@@ -621,6 +623,51 @@ describe("VaultClient identity bootstrap", () => {
     expect(fetchSpy).toHaveBeenCalledTimes(1);
   });
 
+  it("pickCanonicalPersonEntity_picks_oldest_tiebreak_uid", () => {
+    const list: EntityInfo[] = [
+      { uid: "prs_b", slug: "b", type: "person", status: "active", createdAt: "2026-01-02T00:00:00Z" } as EntityInfo,
+      { uid: "prs_a", slug: "a", type: "person", status: "active", createdAt: "2026-01-01T00:00:00Z" } as EntityInfo,
+    ];
+    // Older createdAt wins
+    expect(pickCanonicalPersonEntity(list)?.uid).toBe("prs_a");
+
+    // Same createdAt: uid tiebreak (lexicographic ascending)
+    const tieList: EntityInfo[] = [
+      { uid: "prs_z", slug: "z", type: "person", status: "active", createdAt: "2026-01-01T00:00:00Z" } as EntityInfo,
+      { uid: "prs_a", slug: "a", type: "person", status: "active", createdAt: "2026-01-01T00:00:00Z" } as EntityInfo,
+    ];
+    expect(pickCanonicalPersonEntity(tieList)?.uid).toBe("prs_a");
+  });
+
+  it("pickCanonicalPersonEntity_handles_missing_createdAt_deterministically", () => {
+    // undefined createdAt coalesces to "" which sorts before any ISO date string.
+    // So the entity with undefined createdAt wins on the createdAt comparison.
+    // When two entities both lack createdAt, uid tiebreak applies.
+    const list: EntityInfo[] = [
+      { uid: "prs_b", slug: "b", type: "person", status: "active", createdAt: "2026-01-01T00:00:00Z" } as EntityInfo,
+      { uid: "prs_a", slug: "a", type: "person", status: "active" } as EntityInfo, // no createdAt
+    ];
+    // "" < "2026-..." so prs_a (undefined→"") wins
+    expect(pickCanonicalPersonEntity(list)?.uid).toBe("prs_a");
+
+    // Both undefined: uid tiebreak
+    const bothUndefined: EntityInfo[] = [
+      { uid: "prs_z", slug: "z", type: "person", status: "active" } as EntityInfo,
+      { uid: "prs_a", slug: "a", type: "person", status: "active" } as EntityInfo,
+    ];
+    expect(pickCanonicalPersonEntity(bothUndefined)?.uid).toBe("prs_a");
+  });
+
+  it("pickCanonicalPersonEntity_filters_out_non_person_types", () => {
+    const mixed: EntityInfo[] = [
+      { uid: "cmp_x", slug: "x", type: "company", status: "active", createdAt: "2025-01-01T00:00:00Z" } as EntityInfo,
+      { uid: "prs_b", slug: "b", type: "person", status: "active", createdAt: "2026-01-02T00:00:00Z" } as EntityInfo,
+    ];
+    const result = pickCanonicalPersonEntity(mixed);
+    expect(result?.uid).toBe("prs_b");
+    expect(result?.type).toBe("person");
+  });
+
   it("vendSelf_roundtrip", async () => {
     fetchSpy.mockResolvedValueOnce(
       jsonResponse(200, {

package/src/vault-client.ts

@@ -112,6 +112,23 @@ export interface EntityInfo {
   createdAt: string;
 }
 
+export function pickCanonicalPersonEntity(
+  list: EntityInfo[],
+): EntityInfo | null {
+  // Defensive filter — callers today pass `entity.listByType("person")` so this is
+  // a no-op, but a future caller passing a mixed list would otherwise silently get
+  // back a non-person entity.
+  const persons = list.filter((e) => e.type === "person");
+  if (persons.length === 0) return null;
+  const sorted = [...persons].sort((a, b) => {
+    const ac = (a.createdAt as string | undefined) ?? "";
+    const bc = (b.createdAt as string | undefined) ?? "";
+    if (ac !== bc) return ac < bc ? -1 : 1;
+    return a.uid < b.uid ? -1 : 1;
+  });
+  return sorted[0];
+}
+
 export interface PendingInviteByEmail {
   membershipKey: string;
   companyUid: string;
@@ -344,13 +361,8 @@ export class VaultClient {
     displayName: string;
   }): Promise<EntityInfo> {
     const existing = await this.entity.listByType("person");
-    const sorted = [...existing].sort((a, b) => {
-      const ac = (a.createdAt as string | undefined) ?? "";
-      const bc = (b.createdAt as string | undefined) ?? "";
-      if (ac !== bc) return ac < bc ? -1 : 1;
-      return a.uid < b.uid ? -1 : 1;
-    });
-    if (sorted.length > 0) return sorted[0];
+    const pick = pickCanonicalPersonEntity(existing);
+    if (pick !== null) return pick;
 
     const slug =
       hints.displayName