@indigoai-us/hq-cloud 5.1.9 → 5.1.11

package/src/cli/share.ts

@@ -14,6 +14,7 @@ import { readJournal, writeJournal, hashFile, updateEntry } from "../journal.js"
 import { createIgnoreFilter, isWithinSizeLimit } from "../ignore.js";
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy } from "./conflict.js";
+import type { SyncProgressEvent } from "./sync.js";
 
 export interface ShareOptions {
   /** Path(s) to share (files or directories) */
@@ -28,6 +29,23 @@ export interface ShareOptions {
   vaultConfig: VaultServiceConfig;
   /** HQ root directory */
   hqRoot: string;
+  /**
+   * Per-file event callback. When present, suppresses the default
+   * `console.log`/`console.error` human output — same contract as `sync()`.
+   * This is the seam `hq-sync-runner` uses to stream ndjson for push events.
+   */
+  onEvent?: (event: SyncProgressEvent) => void;
+  /**
+   * When true, files whose local hash matches the journal entry from the
+   * last sync are skipped (no remote HEAD, no upload). This is the gate
+   * that makes "push everything that changed" efficient — without it, a
+   * bidirectional Sync Now would re-upload every file each tick.
+   *
+   * Default false to preserve `hq share <file>` semantics: when a user
+   * explicitly names a file, they expect it to be sent even if the local
+   * hash matches the last-sync state (e.g. to re-heal a bucket).
+   */
+  skipUnchanged?: boolean;
 }
 
 export interface ShareResult {
@@ -41,7 +59,8 @@ export interface ShareResult {
  * Share local file(s) to the entity vault.
  */
 export async function share(options: ShareOptions): Promise<ShareResult> {
-  const { paths, company, message, onConflict, vaultConfig, hqRoot } = options;
+  const { paths, company, message, onConflict, vaultConfig, hqRoot, skipUnchanged } = options;
+  const emit = options.onEvent ?? defaultConsoleLogger;
 
   // Resolve company — slug, UID, or from active config
   const companyRef = company ?? resolveActiveCompany(hqRoot);
@@ -54,6 +73,10 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
   // Resolve entity context (handles STS vending + caching)
   let ctx = await resolveEntityContext(companyRef, vaultConfig);
+  // Remote keys are company-relative; the on-disk scoping prefix is
+  // companies/{slug}/. Anything outside this folder gets skipped to avoid
+  // leaking cross-company state into the vault.
+  const syncRoot = path.join(hqRoot, "companies", ctx.slug);
   const shouldSync = createIgnoreFilter(hqRoot);
   const journal = readJournal(ctx.slug);
 
@@ -62,15 +85,32 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   let filesSkipped = 0;
 
   // Collect all files to share
-  const filesToShare = collectFiles(paths, hqRoot, shouldSync);
+  const filesToShare = collectFiles(paths, hqRoot, syncRoot, shouldSync);
 
   for (const { absolutePath, relativePath } of filesToShare) {
     if (!isWithinSizeLimit(absolutePath)) {
-      console.error(`  Skipped (too large): ${relativePath}`);
+      emit({
+        type: "error",
+        path: relativePath,
+        message: "file exceeds size limit",
+      });
       filesSkipped++;
       continue;
     }
 
+    // Skip-if-unchanged gate: the hot path for bidirectional Sync Now. When
+    // walking an entire company folder, this is what keeps us from re-uploading
+    // every file every tick. Off by default so `hq share <file>` keeps its
+    // explicit-intent semantics (user named it, user wants it sent).
+    const localHash = hashFile(absolutePath);
+    if (skipUnchanged) {
+      const existing = journal.files[relativePath];
+      if (existing && existing.hash === localHash) {
+        filesSkipped++;
+        continue;
+      }
+    }
+
     // Auto-refresh context if credentials expiring
     if (isExpiringSoon(ctx.expiresAt)) {
       ctx = await refreshEntityContext(companyRef, vaultConfig);
@@ -80,7 +120,6 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     const remoteMeta = await headRemoteFile(ctx, relativePath);
     if (remoteMeta) {
       const journalEntry = journal.files[relativePath];
-      const localHash = hashFile(absolutePath);
 
       // If remote has changed since our last sync, it's a conflict
       if (journalEntry && journalEntry.hash !== localHash) {
@@ -109,12 +148,11 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     // Upload
     try {
       const stat = fs.statSync(absolutePath);
-      const hash = hashFile(absolutePath);
 
       await uploadFile(ctx, absolutePath, relativePath);
 
       // Update journal with optional message
-      updateEntry(journal, relativePath, hash, stat.size, "up");
+      updateEntry(journal, relativePath, localHash, stat.size, "up");
       if (message) {
         journal.files[relativePath] = {
           ...journal.files[relativePath],
@@ -124,11 +162,18 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
       filesUploaded++;
       bytesUploaded += stat.size;
-      console.log(`  ✓ ${relativePath}`);
+      emit({
+        type: "progress",
+        path: relativePath,
+        bytes: stat.size,
+        ...(message ? { message } : {}),
+      });
     } catch (err) {
-      console.error(
-        `  ✗ ${relativePath} — ${err instanceof Error ? err.message : err}`,
-      );
+      emit({
+        type: "error",
+        path: relativePath,
+        message: err instanceof Error ? err.message : String(err),
+      });
     }
   }
 
@@ -137,6 +182,22 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   return { filesUploaded, bytesUploaded, filesSkipped, aborted: false };
 }
 
+/**
+ * Default human-readable share output. Preserves the exact format the CLI
+ * emitted before `onEvent` was added — tty users see no change.
+ */
+function defaultConsoleLogger(event: SyncProgressEvent): void {
+  if (event.type === "progress") {
+    if (event.message) {
+      console.log(`  ✓ ${event.path} — "${event.message}"`);
+    } else {
+      console.log(`  ✓ ${event.path}`);
+    }
+  } else {
+    console.error(`  ✗ ${event.path} — ${event.message}`);
+  }
+}
+
 /**
  * Resolve active company from .hq/config.json or parent directory chain.
  */
@@ -155,10 +216,15 @@ function resolveActiveCompany(hqRoot: string): string | undefined {
 
 /**
  * Collect files from paths (expanding directories recursively).
+ *
+ * Remote S3 keys are computed relative to `syncRoot` (companies/{slug}/), not
+ * `hqRoot`. Files outside `syncRoot` are skipped with a warning — sharing
+ * anything outside a company's folder would leak state into the wrong vault.
  */
 function collectFiles(
   paths: string[],
   hqRoot: string,
+  syncRoot: string,
   filter: (p: string) => boolean,
 ): { absolutePath: string; relativePath: string }[] {
   const results: { absolutePath: string; relativePath: string }[] = [];
@@ -171,11 +237,16 @@ function collectFiles(
       continue;
     }
 
+    if (!isWithin(syncRoot, absolutePath)) {
+      console.error(`  Warning: ${p} is outside company folder, skipping.`);
+      continue;
+    }
+
     const stat = fs.statSync(absolutePath);
     if (stat.isDirectory()) {
-      results.push(...walkDir(absolutePath, hqRoot, filter));
+      results.push(...walkDir(absolutePath, syncRoot, filter));
     } else if (stat.isFile()) {
-      const relativePath = path.relative(hqRoot, absolutePath);
+      const relativePath = path.relative(syncRoot, absolutePath);
       if (filter(absolutePath)) {
         results.push({ absolutePath, relativePath });
       }
@@ -187,7 +258,7 @@ function collectFiles(
 
 function walkDir(
   dir: string,
-  root: string,
+  syncRoot: string,
   filter: (p: string) => boolean,
 ): { absolutePath: string; relativePath: string }[] {
   const results: { absolutePath: string; relativePath: string }[] = [];
@@ -199,14 +270,19 @@ function walkDir(
     if (!filter(absolutePath)) continue;
 
     if (entry.isDirectory()) {
-      results.push(...walkDir(absolutePath, root, filter));
+      results.push(...walkDir(absolutePath, syncRoot, filter));
     } else if (entry.isFile()) {
       results.push({
         absolutePath,
-        relativePath: path.relative(root, absolutePath),
+        relativePath: path.relative(syncRoot, absolutePath),
       });
     }
   }
 
   return results;
 }
+
+function isWithin(parent: string, child: string): boolean {
+  const rel = path.relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}

package/src/cli/sync.test.ts

@@ -61,7 +61,7 @@ const mockVendResponse = {
 function setupFetchMock() {
   const fetchMock = vi.fn().mockImplementation(async (url: string) => {
     const urlStr = String(url);
-    if (urlStr.includes("/entity/by-slug/")) {
+    if (urlStr.includes("/entity/by-slug/") || /\/entity\/cmp_/.test(urlStr)) {
       return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
     }
     if (urlStr.includes("/sts/vend")) {
@@ -98,7 +98,7 @@ describe("sync", () => {
     delete process.env.HQ_STATE_DIR;
   });
 
-  it("downloads remote files that don't exist locally", async () => {
+  it("downloads remote files under companies/{slug}/ so two companies don't collide", async () => {
     const result = await sync({
       company: "acme",
       vaultConfig: mockConfig,
@@ -107,8 +107,26 @@ describe("sync", () => {
 
     expect(result.filesDownloaded).toBe(2);
     expect(result.aborted).toBe(false);
-    expect(fs.existsSync(path.join(tmpDir, "docs", "handoff.md"))).toBe(true);
-    expect(fs.existsSync(path.join(tmpDir, "knowledge", "readme.md"))).toBe(true);
+    // Scoped under companies/{slug}/
+    expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "docs", "handoff.md"))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "knowledge", "readme.md"))).toBe(true);
+    // NOT at hqRoot (pre-fix behavior would have written here and clobbered across companies)
+    expect(fs.existsSync(path.join(tmpDir, "docs", "handoff.md"))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, "knowledge", "readme.md"))).toBe(false);
+  });
+
+  it("scopes by resolved ctx.slug even when caller passes a UID", async () => {
+    // mockEntity.slug is "acme" regardless of the ref used; verify resolved
+    // slug drives the local path, not the caller's ref.
+    const result = await sync({
+      company: "cmp_01ABCDEF",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    expect(result.filesDownloaded).toBe(2);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "docs", "handoff.md"))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "cmp_01ABCDEF", "docs", "handoff.md"))).toBe(false);
   });
 
   it("throws when no company specified and no active company", async () => {
@@ -129,8 +147,9 @@ describe("sync", () => {
   });
 
   it("detects conflicts with local changes and keeps local on --on-conflict keep", async () => {
-    fs.mkdirSync(path.join(tmpDir, "docs"), { recursive: true });
-    fs.writeFileSync(path.join(tmpDir, "docs", "handoff.md"), "local version");
+    const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+    fs.mkdirSync(companyDocs, { recursive: true });
+    fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
 
     fs.writeFileSync(
       journalPath,
@@ -157,12 +176,13 @@ describe("sync", () => {
 
     expect(result.conflicts).toBe(1);
     expect(result.filesSkipped).toBeGreaterThanOrEqual(1);
-    expect(fs.readFileSync(path.join(tmpDir, "docs", "handoff.md"), "utf-8")).toBe("local version");
+    expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("local version");
   });
 
   it("aborts on --on-conflict abort", async () => {
-    fs.mkdirSync(path.join(tmpDir, "docs"), { recursive: true });
-    fs.writeFileSync(path.join(tmpDir, "docs", "handoff.md"), "local version");
+    const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+    fs.mkdirSync(companyDocs, { recursive: true });
+    fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
 
     fs.writeFileSync(
       journalPath,
@@ -191,8 +211,9 @@ describe("sync", () => {
   });
 
   it("overwrites local on --on-conflict overwrite", async () => {
-    fs.mkdirSync(path.join(tmpDir, "docs"), { recursive: true });
-    fs.writeFileSync(path.join(tmpDir, "docs", "handoff.md"), "local version");
+    const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+    fs.mkdirSync(companyDocs, { recursive: true });
+    fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
 
     fs.writeFileSync(
       journalPath,
@@ -220,6 +241,6 @@ describe("sync", () => {
     expect(result.conflicts).toBe(1);
     expect(result.filesDownloaded).toBeGreaterThanOrEqual(1);
     // File should be overwritten with mock content
-    expect(fs.readFileSync(path.join(tmpDir, "docs", "handoff.md"), "utf-8")).toBe("mock file content");
+    expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("mock file content");
   });
 });

package/src/cli/sync.ts

@@ -74,6 +74,11 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
 
   // Resolve entity context
   let ctx = await resolveEntityContext(companyRef, vaultConfig);
+  // Every company's files land under companies/{slug}/ so fanning out multiple
+  // 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);
   const shouldSync = createIgnoreFilter(hqRoot);
   const journal = readJournal(ctx.slug);
 
@@ -86,7 +91,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   const remoteFiles = await listRemoteFiles(ctx);
 
   for (const remoteFile of remoteFiles) {
-    const localPath = path.join(hqRoot, remoteFile.key);
+    const localPath = path.join(companyRoot, remoteFile.key);
 
     // Apply ignore rules
     if (!shouldSync(localPath)) {

package/src/cognito-auth.test.ts

@@ -1,9 +1,9 @@
 /**
  * Unit tests for cognito-auth.ts — focus on the `expiresAt` shape contract.
  *
- * Canonical on-disk shape is ISO 8601 (what both writers emit). The reader
- * also tolerates a raw number (ms since epoch) for forward/backward compat
- * during rollouts, and fails safe on anything unparseable.
+ * Canonical on-disk shape is epoch milliseconds (number). The reader also
+ * tolerates ISO 8601 strings for backward compatibility with pre-migration
+ * token files, and fails safe on anything unparseable.
  */
 
 import * as fs from "fs";
@@ -100,11 +100,21 @@ describe("isExpiring — expiresAt shape tolerance", () => {
 });
 
 // ---------------------------------------------------------------------------
-// Round-trip: writers emit ISO, readers read ISO
+// Round-trip: writers emit epoch-ms, readers read epoch-ms
 // ---------------------------------------------------------------------------
 
 describe("expiresAt shape round-trip", () => {
-  it("saveCachedTokens + loadCachedTokens preserves ISO string shape", async () => {
+  it("saveCachedTokens + loadCachedTokens preserves epoch-ms number shape", async () => {
+    const { saveCachedTokens, loadCachedTokens } = await importModule();
+    const epochMs = Date.now() + 3600 * 1000;
+    saveCachedTokens({ ...baseTokens, expiresAt: epochMs });
+    const loaded = loadCachedTokens();
+    expect(loaded).not.toBeNull();
+    expect(typeof loaded?.expiresAt).toBe("number");
+    expect(loaded?.expiresAt).toBe(epochMs);
+  });
+
+  it("saveCachedTokens + loadCachedTokens tolerates legacy ISO string", async () => {
     const { saveCachedTokens, loadCachedTokens } = await importModule();
     const iso = new Date(Date.now() + 3600 * 1000).toISOString();
     saveCachedTokens({ ...baseTokens, expiresAt: iso });
@@ -112,12 +122,9 @@ describe("expiresAt shape round-trip", () => {
     expect(loaded).not.toBeNull();
     expect(typeof loaded?.expiresAt).toBe("string");
     expect(loaded?.expiresAt).toBe(iso);
-    expect(loaded?.expiresAt).toMatch(
-      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/,
-    );
   });
 
-  it("refreshTokens writes an ISO string to cache", async () => {
+  it("refreshTokens writes epoch milliseconds to cache", async () => {
     vi.stubGlobal(
       "fetch",
       vi.fn(async () =>
@@ -135,6 +142,7 @@ describe("expiresAt shape round-trip", () => {
     );
 
     const { refreshTokens, loadCachedTokens } = await importModule();
+    const before = Date.now();
     const result = await refreshTokens(
       {
         region: "us-east-1",
@@ -143,14 +151,14 @@ describe("expiresAt shape round-trip", () => {
       },
       "prior-refresh-token",
     );
+    const after = Date.now();
 
-    expect(typeof result.expiresAt).toBe("string");
-    expect(result.expiresAt).toMatch(
-      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/,
-    );
+    expect(typeof result.expiresAt).toBe("number");
+    expect(result.expiresAt).toBeGreaterThanOrEqual(before + 3600 * 1000);
+    expect(result.expiresAt).toBeLessThanOrEqual(after + 3600 * 1000);
 
     const onDisk = loadCachedTokens();
     expect(onDisk?.expiresAt).toBe(result.expiresAt);
-    expect(typeof onDisk?.expiresAt).toBe("string");
+    expect(typeof onDisk?.expiresAt).toBe("number");
   });
 });

package/src/cognito-auth.ts

@@ -38,14 +38,25 @@ export interface CognitoAuthConfig {
   port?: number;
   /** OAuth scopes. Defaults to ["openid", "email", "profile"]. */
   scopes?: string[];
+  /**
+   * Force a federated IdP (e.g. "Google"). When set, the Hosted UI IdP picker
+   * is bypassed and Cognito redirects straight to the provider. When omitted,
+   * Cognito shows its default picker.
+   */
+  identityProvider?: string;
+  /**
+   * OAuth `prompt` param (e.g. "select_account"). Only meaningful when the IdP
+   * honors it — Google uses it to force account re-selection.
+   */
+  prompt?: string;
 }
 
 export interface CognitoTokens {
   accessToken: string;
   idToken: string;
   refreshToken: string;
-  /** ISO 8601 timestamp when the access token expires. */
-  expiresAt: string;
+  /** Epoch milliseconds when the access token expires. Writers MUST emit a number. Readers accept ISO 8601 strings for backward compatibility with pre-migration token files. */
+  expiresAt: string | number;
   tokenType: "Bearer";
 }
 
@@ -78,7 +89,9 @@ export function saveCachedTokens(tokens: CognitoTokens): void {
   if (!fs.existsSync(HQ_DIR)) {
     fs.mkdirSync(HQ_DIR, { recursive: true, mode: 0o700 });
   }
-  fs.writeFileSync(TOKEN_FILE, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+  const tmpPath = path.join(HQ_DIR, `.cognito-tokens.json.tmp.${process.pid}`);
+  fs.writeFileSync(tmpPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+  fs.renameSync(tmpPath, TOKEN_FILE);
 }
 
 export function clearCachedTokens(): void {
@@ -86,11 +99,10 @@ export function clearCachedTokens(): void {
 }
 
 /**
- * Parse `expiresAt` to epoch-ms. Canonical on-disk shape is ISO 8601 (what
- * both writers in this file emit), but older/external writers may have left a
- * raw number. Accept both so a shape mismatch during rollout doesn't wedge
- * sign-in. Returns null for anything unparseable — callers should treat that
- * as "expired" and force a refresh.
+ * Parse `expiresAt` to epoch-ms. Canonical on-disk shape is epoch milliseconds
+ * (number). Older token files may contain ISO 8601 strings. Accept both for
+ * migration safety. Returns null for anything unparseable — callers should
+ * treat that as "expired" and force a refresh.
  */
 function parseExpiresAtMs(raw: unknown): number | null {
   if (typeof raw === "number") return Number.isFinite(raw) ? raw : null;
@@ -158,7 +170,9 @@ export async function browserLogin(
   const { verifier, challenge } = generatePkce();
   const state = base64UrlEncode(crypto.randomBytes(16));
 
-  const authUrl = new URL(`${authBaseUrl(config)}/login`);
+  // Use `/oauth2/authorize` (not `/login`) so `identity_provider` + `prompt`
+  // are honored. `/login` ignores those params and always shows the IdP picker.
+  const authUrl = new URL(`${authBaseUrl(config)}/oauth2/authorize`);
   authUrl.searchParams.set("client_id", config.clientId);
   authUrl.searchParams.set("response_type", "code");
   authUrl.searchParams.set("scope", scopes);
@@ -166,6 +180,12 @@ export async function browserLogin(
   authUrl.searchParams.set("code_challenge", challenge);
   authUrl.searchParams.set("code_challenge_method", "S256");
   authUrl.searchParams.set("state", state);
+  if (config.identityProvider) {
+    authUrl.searchParams.set("identity_provider", config.identityProvider);
+  }
+  if (config.prompt) {
+    authUrl.searchParams.set("prompt", config.prompt);
+  }
 
   const code = await waitForAuthCode(port, state);
   const tokens = await exchangeCodeForTokens(config, code, verifier, port);
@@ -300,7 +320,7 @@ async function exchangeCodeForTokens(
     accessToken: data.access_token,
     idToken: data.id_token,
     refreshToken: data.refresh_token,
-    expiresAt: new Date(Date.now() + data.expires_in * 1000).toISOString(),
+    expiresAt: Date.now() + data.expires_in * 1000,
     tokenType: "Bearer",
   };
 }
@@ -336,7 +356,7 @@ export async function refreshTokens(
     accessToken: data.access_token,
     idToken: data.id_token,
     refreshToken: data.refresh_token ?? currentRefreshToken,
-    expiresAt: new Date(Date.now() + data.expires_in * 1000).toISOString(),
+    expiresAt: Date.now() + data.expires_in * 1000,
     tokenType: "Bearer",
   };
   saveCachedTokens(tokens);

package/src/vault-client.test.ts

@@ -560,4 +560,64 @@ describe("VaultClient identity bootstrap", () => {
     const body = JSON.parse(init.body as string);
     expect(body.slug).toBe("user-12345678");
   });
+
+  it("listByType_roundtrips_createdAt", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          {
+            uid: "prs_x",
+            slug: "alice",
+            type: "person",
+            status: "active",
+            createdAt: "2026-01-01T00:00:00Z",
+          },
+        ],
+      }),
+    );
+
+    const entities = await client.entity.listByType("person");
+    expect(entities).toHaveLength(1);
+    expect(entities[0].createdAt).toBe("2026-01-01T00:00:00Z");
+  });
+
+  it("ensureMyPersonEntity_picks_oldest_when_multiple", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          { uid: "prs_b", slug: "b", type: "person", status: "active", createdAt: "2026-03-01T00:00:00Z" },
+          { uid: "prs_a", slug: "a", type: "person", status: "active", createdAt: "2026-01-01T00:00:00Z" },
+          { uid: "prs_c", slug: "c", type: "person", status: "active", createdAt: "2026-06-01T00:00:00Z" },
+        ],
+      }),
+    );
+
+    const person = await client.ensureMyPersonEntity({
+      ownerSub: "sub-multi",
+      displayName: "Multi User",
+    });
+
+    expect(person.uid).toBe("prs_a");
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("ensureMyPersonEntity_handles_missing_createdAt_deterministically", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          { uid: "prs_z", slug: "z", type: "person", status: "active" },
+          { uid: "prs_a", slug: "a", type: "person", status: "active" },
+        ],
+      }),
+    );
+
+    const person = await client.ensureMyPersonEntity({
+      ownerSub: "sub-nodates",
+      displayName: "No Dates User",
+    });
+
+    // Both missing createdAt → "" tie, uid tiebreak selects prs_a
+    expect(person.uid).toBe("prs_a");
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
 });

package/src/vault-client.ts

@@ -109,6 +109,7 @@ export interface EntityInfo {
   name?: string;
   bucketName?: string;
   status: string;
+  createdAt: string;
 }
 
 export interface PendingInviteByEmail {
@@ -343,7 +344,13 @@ export class VaultClient {
     displayName: string;
   }): Promise<EntityInfo> {
     const existing = await this.entity.listByType("person");
-    if (existing.length > 0) return existing[0];
+    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 slug =
       hints.displayName

package/test/invite-flow.integration.test.ts

@@ -57,7 +57,7 @@ describe("parseToken", () => {
   });
 
   it("extracts token from https:// URL", () => {
-    expect(parseToken("https://hq.indigoai.com/accept/tok_xyz")).toBe("tok_xyz");
+    expect(parseToken("https://example.com/accept/tok_xyz")).toBe("tok_xyz");
   });
 
   it("returns raw token unchanged", () => {