@indigoai-us/hq-cli 5.14.0 → 5.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.14.0",
+  "version": "5.15.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -29,8 +29,9 @@
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
+    "@types/semver": "^7.5.8",
     "typescript": "^5.7.0",
-    "@types/semver": "^7.5.8"
+    "vitest": "^4.1.2"
   },
   "repository": {
     "type": "git",

package/src/commands/cloud-provision.test.ts

@@ -24,6 +24,7 @@ import {
   companyConfigPath,
   companyDirPath,
   createDefaultVaultClient,
+  ensureManifestEntryForProvision,
   manifestPath,
   patchManifest,
   provisionCompany,
@@ -92,6 +93,28 @@ describe("validateSlug", () => {
     expect(() => validateSlug("acme$co")).toThrowError(/Invalid slug/);
   });
 
+  it('rejects the path-traversal slug "."', () => {
+    try {
+      validateSlug(".");
+      expect.fail("should have thrown");
+    } catch (e) {
+      expect(e).toBeInstanceOf(ProvisionError);
+      expect((e as ProvisionError).code).toBe(2);
+      expect((e as ProvisionError).message).toMatch(/path-traversal/);
+    }
+  });
+
+  it('rejects the path-traversal slug ".."', () => {
+    try {
+      validateSlug("..");
+      expect.fail("should have thrown");
+    } catch (e) {
+      expect(e).toBeInstanceOf(ProvisionError);
+      expect((e as ProvisionError).code).toBe(2);
+      expect((e as ProvisionError).message).toMatch(/path-traversal/);
+    }
+  });
+
   it('rejects the reserved "personal" slug', () => {
     expect(() => validateSlug("personal")).toThrowError(/reserved/);
     try {
@@ -169,6 +192,129 @@ describe("validateManifestAndDir", () => {
   });
 });
 
+// ── ensureManifestEntryForProvision ──────────────────────────────────────────
+
+describe("ensureManifestEntryForProvision", () => {
+  it("inserts an empty entry when slug is missing but company dir exists", () => {
+    seedManifest(tmpRoot, { other: { status: "active" } });
+    seedCompanyDir(tmpRoot, "indigo");
+    ensureManifestEntryForProvision(tmpRoot, "indigo");
+    const onDisk = yaml.load(
+      fs.readFileSync(manifestPath(tmpRoot), "utf-8"),
+    ) as { companies: Record<string, unknown> };
+    expect(onDisk.companies.indigo).toEqual({});
+    expect(onDisk.companies.other).toEqual({ status: "active" });
+  });
+
+  it("validateManifestAndDir then succeeds for the auto-inserted slug", () => {
+    seedManifest(tmpRoot, { other: { status: "active" } });
+    seedCompanyDir(tmpRoot, "indigo");
+    ensureManifestEntryForProvision(tmpRoot, "indigo");
+    const { manifest } = validateManifestAndDir(tmpRoot, "indigo");
+    expect(manifest.companies?.indigo).toEqual({});
+  });
+
+  it("is idempotent — re-run on an already-present entry is a no-op", () => {
+    seedManifest(tmpRoot, { indigo: { status: "active" } });
+    seedCompanyDir(tmpRoot, "indigo");
+    const before = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    ensureManifestEntryForProvision(tmpRoot, "indigo");
+    const after = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    expect(after).toBe(before);
+  });
+
+  it("does NOT insert when company dir is missing (no typo masking)", () => {
+    seedManifest(tmpRoot, { other: { status: "active" } });
+    // No seedCompanyDir — slug looks like a typo.
+    const before = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    ensureManifestEntryForProvision(tmpRoot, "indigo");
+    const after = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    expect(after).toBe(before);
+    // Downstream validateManifestAndDir still throws — dir-missing wins over
+    // slug-missing in the error message because the dir check runs later, but
+    // either way the user gets exit 2 with no silent mutation.
+    expect(() => validateManifestAndDir(tmpRoot, "indigo")).toThrow();
+  });
+
+  it("does NOT insert when companies/<slug> exists as a regular file (not a dir)", () => {
+    seedManifest(tmpRoot, { other: { status: "active" } });
+    // Create a regular file at companies/indigo (not a directory). Without
+    // the isDirectory() guard, existsSync would return true and the helper
+    // would auto-insert — then provisionCompany would create the vault
+    // entity + patch manifest BEFORE writeCompanyConfig's mkdir failed with
+    // ENOTDIR. Verify no mutation.
+    const companiesDir = path.join(tmpRoot, "companies");
+    fs.mkdirSync(companiesDir, { recursive: true });
+    fs.writeFileSync(path.join(companiesDir, "indigo"), "not a directory");
+    const before = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    ensureManifestEntryForProvision(tmpRoot, "indigo");
+    const after = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    expect(after).toBe(before);
+  });
+
+  it("does NOT insert when manifest file is missing entirely", () => {
+    seedCompanyDir(tmpRoot, "indigo");
+    expect(() =>
+      ensureManifestEntryForProvision(tmpRoot, "indigo"),
+    ).not.toThrow();
+    expect(fs.existsSync(manifestPath(tmpRoot))).toBe(false);
+  });
+
+  it("does NOT insert when manifest is malformed (no .companies map)", () => {
+    const mPath = manifestPath(tmpRoot);
+    fs.mkdirSync(path.dirname(mPath), { recursive: true });
+    const malformed = "not_companies: 'oops'\n";
+    fs.writeFileSync(mPath, malformed);
+    seedCompanyDir(tmpRoot, "indigo");
+    ensureManifestEntryForProvision(tmpRoot, "indigo");
+    // File on disk unchanged — malformed manifests are left for validation
+    // to surface, not silently rewritten.
+    expect(fs.readFileSync(mPath, "utf-8")).toBe(malformed);
+  });
+
+  it("preserves a null entry (does not promote null → {})", () => {
+    seedManifest(tmpRoot, { indigo: null });
+    seedCompanyDir(tmpRoot, "indigo");
+    ensureManifestEntryForProvision(tmpRoot, "indigo");
+    const onDisk = yaml.load(
+      fs.readFileSync(manifestPath(tmpRoot), "utf-8"),
+    ) as { companies: Record<string, unknown> };
+    expect(onDisk.companies.indigo).toBeNull();
+  });
+
+  it('refuses to auto-insert for path-traversal slug "." (defense-in-depth)', () => {
+    seedManifest(tmpRoot, { other: { status: "active" } });
+    // `companies/.` resolves to `companies/` itself, which DOES exist on
+    // disk — without the path-resolve guard, the helper would insert
+    // `".": {}` into the manifest. Verify it doesn't.
+    const before = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    ensureManifestEntryForProvision(tmpRoot, ".");
+    const after = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    expect(after).toBe(before);
+  });
+
+  it('refuses to auto-insert for path-traversal slug ".." (defense-in-depth)', () => {
+    seedManifest(tmpRoot, { other: { status: "active" } });
+    // `companies/..` resolves to `tmpRoot` itself, which exists — without
+    // the path-resolve guard, the helper would insert `"..": {}` into the
+    // manifest. Verify it doesn't.
+    const before = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    ensureManifestEntryForProvision(tmpRoot, "..");
+    const after = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    expect(after).toBe(before);
+  });
+
+  it("refuses to auto-insert when slug contains a path separator", () => {
+    seedManifest(tmpRoot, { other: { status: "active" } });
+    // Even if validateSlug were bypassed, a slug like `foo/bar` would land
+    // in a nested path; the path-resolve guard rejects it.
+    const before = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    ensureManifestEntryForProvision(tmpRoot, "foo/bar");
+    const after = fs.readFileSync(manifestPath(tmpRoot), "utf-8");
+    expect(after).toBe(before);
+  });
+});
+
 // ── patchManifest ────────────────────────────────────────────────────────────
 
 describe("patchManifest", () => {
@@ -433,6 +579,9 @@ describe("provisionCompany", () => {
 
   function makeVaultClient(overrides: Partial<VaultClient> = {}): VaultClient {
     return {
+      listMyPersonEntities: vi.fn().mockResolvedValue([
+        { uid: "prs_01H", type: "person", slug: "test-user", name: "Test User" },
+      ]),
       findCompanyBySlug: vi.fn().mockResolvedValue(null),
       createCompanyEntity: vi.fn(),
       ...overrides,
@@ -495,6 +644,67 @@ describe("provisionCompany", () => {
     expect(vaultClient.createCompanyEntity).toHaveBeenCalledOnce();
   });
 
+  it("folder-only path — slug missing from manifest but dir exists → auto-insert → succeeds", async () => {
+    // The hq-sync Connect dead-end this PR fixes: companies/indigo/ exists on
+    // disk, the user clicks Connect, but indigo isn't under .companies yet.
+    seedManifest(tmpRoot, { other: { status: "active" } });
+    seedCompanyDir(tmpRoot, "indigo");
+    const entity: VaultEntity = {
+      uid: "cmp_02H",
+      type: "company",
+      slug: "indigo",
+      name: "Indigo",
+      bucketName: "hq-vault-cmp-02H",
+      kmsKeyId: null,
+    };
+    const vaultClient = makeVaultClient({
+      findCompanyBySlug: vi.fn().mockResolvedValue(null),
+      createCompanyEntity: vi.fn().mockResolvedValue(entity),
+    });
+    const result = await provisionCompany({
+      slug: "indigo",
+      name: "Indigo",
+      hqRoot: tmpRoot,
+      vaultApiUrl,
+      vaultClient,
+      resolveAccessToken: async () => accessToken,
+      runInitialSync: vi
+        .fn()
+        .mockResolvedValue({ filesUploaded: 0, bytesUploaded: 0 }),
+      log: () => {},
+    });
+    expect(result.ok).toBe(true);
+    expect(result.created_entity).toBe(true);
+    expect(result.manifest_patched).toBe(true);
+    const m = yaml.load(fs.readFileSync(manifestPath(tmpRoot), "utf-8")) as {
+      companies: Record<string, Record<string, unknown>>;
+    };
+    expect(m.companies.indigo.cloud_uid).toBe("cmp_02H");
+    expect(m.companies.indigo.bucket_name).toBe("hq-vault-cmp-02H");
+    // Sibling untouched.
+    expect(m.companies.other).toEqual({ status: "active" });
+  });
+
+  it("typo guard — slug missing AND dir missing still throws code 2 (no auto-heal)", async () => {
+    seedManifest(tmpRoot, { other: { status: "active" } });
+    // NOT calling seedCompanyDir — a slug with no folder is a typo.
+    await expect(
+      provisionCompany({
+        slug: "tyypo",
+        hqRoot: tmpRoot,
+        vaultApiUrl,
+        vaultClient: makeVaultClient(),
+        resolveAccessToken: async () => accessToken,
+        log: () => {},
+      }),
+    ).rejects.toMatchObject({ code: 2 });
+    // Manifest unchanged — typo did not silently insert an entry.
+    const m = yaml.load(fs.readFileSync(manifestPath(tmpRoot), "utf-8")) as {
+      companies: Record<string, unknown>;
+    };
+    expect(m.companies.tyypo).toBeUndefined();
+  });
+
   it("idempotent path — entity found → no POST → still patches + syncs → created_entity=false", async () => {
     setupValid();
     const entity: VaultEntity = {
@@ -720,4 +930,85 @@ describe("provisionCompany", () => {
     expect(c.companyUid).toBe("cmp_SKIP");
     expect(c.bucketName).toBe("hq-vault-cmp-SKIP");
   });
+
+  // ── Pre-flight: caller MUST have a person entity ─────────────────────────
+  //
+  // Without one, the initial-sync step at the end of provision returns 403
+  // "no person entity" from /sts/vend and leaves the operator with a half-
+  // built cloud company. The pre-flight catches this BEFORE any cloud-side
+  // resource creation. Documented in the 2026-05-14 setup-session deep dive.
+
+  it("pre-flight fails fast with code 2 when caller has no person entity — no resources touched", async () => {
+    setupValid();
+    const createCompanyEntity = vi.fn();
+    const runInitialSync = vi.fn();
+    const vaultClient = makeVaultClient({
+      listMyPersonEntities: vi.fn().mockResolvedValue([]),
+      findCompanyBySlug: vi.fn(),
+      createCompanyEntity,
+    });
+
+    let caught: unknown;
+    try {
+      await provisionCompany({
+        slug: "indigo",
+        hqRoot: tmpRoot,
+        vaultApiUrl,
+        vaultClient,
+        resolveAccessToken: async () => accessToken,
+        runInitialSync,
+        log: () => {},
+      });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeInstanceOf(ProvisionError);
+    expect((caught as ProvisionError).code).toBe(2);
+    expect((caught as ProvisionError).message).toMatch(/No person entity/);
+    expect((caught as ProvisionError).message).toMatch(/hq onboard/);
+
+    // No cloud-side mutations: no entity lookup, no entity creation, no sync.
+    expect(vaultClient.findCompanyBySlug).not.toHaveBeenCalled();
+    expect(createCompanyEntity).not.toHaveBeenCalled();
+    expect(runInitialSync).not.toHaveBeenCalled();
+
+    // No disk-side mutations: manifest still untouched.
+    const m = yaml.load(fs.readFileSync(manifestPath(tmpRoot), "utf-8")) as {
+      companies: Record<string, Record<string, unknown>>;
+    };
+    expect(m.companies.indigo.cloud_uid).toBeUndefined();
+    expect(m.companies.indigo.bucket_name).toBeUndefined();
+    expect(fs.existsSync(companyConfigPath(tmpRoot, "indigo"))).toBe(false);
+  });
+
+  it("pre-flight passes when caller has a person entity — flow continues to provisioning", async () => {
+    setupValid();
+    const entity: VaultEntity = {
+      uid: "cmp_OK", type: "company", slug: "indigo", name: "Indigo",
+      bucketName: "hq-vault-cmp-OK", kmsKeyId: "key-OK",
+    };
+    const listSpy = vi.fn().mockResolvedValue([
+      { uid: "prs_known", type: "person", slug: "joey-muller", name: "Joey Muller" },
+    ]);
+    const vaultClient = makeVaultClient({
+      listMyPersonEntities: listSpy,
+      findCompanyBySlug: vi.fn().mockResolvedValue(null),
+      createCompanyEntity: vi.fn().mockResolvedValue(entity),
+    });
+
+    const result = await provisionCompany({
+      slug: "indigo",
+      hqRoot: tmpRoot,
+      vaultApiUrl,
+      vaultClient,
+      resolveAccessToken: async () => accessToken,
+      runInitialSync: async () => ({ filesUploaded: 0, bytesUploaded: 0 }),
+      log: () => {},
+    });
+
+    expect(listSpy).toHaveBeenCalledOnce();
+    expect(result.ok).toBe(true);
+    expect(result.cloud_uid).toBe("cmp_OK");
+  });
 });

package/src/commands/cloud-provision.ts

@@ -20,7 +20,10 @@
  * Exit codes:
  *   0 — success (and `initial_sync.ok=true`)
  *   1 — vault auth/network/API error (no entity provisioned)
- *   2 — invalid slug, company missing from manifest, or company dir missing
+ *   2 — invalid slug, company dir missing, or company is status=archived.
+ *       Folder-only states (companies/<slug>/ exists on disk but no manifest
+ *       entry) self-heal via ensureManifestEntryForProvision before
+ *       validation runs, so a missing manifest entry alone is NOT an exit-2.
  *   3 — sync failure after entity provisioned (cloud_uid in JSON;
  *       `initial_sync.ok=false`). Manifest + config may have been written.
  */
@@ -121,6 +124,15 @@ interface InitialSyncArgs {
 
 /** Vault HTTP client interface — minimal surface for entity ops. */
 export interface VaultClient {
+  /**
+   * List every person entity visible to the caller (scoped server-side by the
+   * caller's Cognito identity). Used by `provisionCompany` as a pre-flight
+   * to verify the caller has been onboarded before mutating any cloud-side
+   * resources — the initial-sync step at the end of provision needs to vend
+   * STS credentials, which the server only does for callers with a person
+   * entity.
+   */
+  listMyPersonEntities(): Promise<VaultEntity[]>;
   findCompanyBySlug(slug: string): Promise<VaultEntity | null>;
   createCompanyEntity(input: {
     slug: string;
@@ -144,12 +156,14 @@ export class ProvisionError extends Error {
 // ── Validation ───────────────────────────────────────────────────────────────
 
 const SLUG_REGEX = /^[A-Za-z0-9._-]+$/;
-const FORBIDDEN_SLUGS = new Set(["personal"]);
+const FORBIDDEN_SLUGS = new Set(["personal", ".", ".."]);
 
 /**
  * Validate a company slug per the contract: alphanumeric / dot / dash / underscore,
- * non-empty, and never `"personal"` (which is auto-provisioned per-user, not
- * promoted via this subcommand).
+ * non-empty, never `"."` or `".."` (path-traversal — would resolve to
+ * `companies/` itself or `<hqRoot>` and write outside the intended company
+ * directory), and never `"personal"` (auto-provisioned per-user, not promoted
+ * via this subcommand).
  *
  * Throws ProvisionError with code=2 on failure.
  */
@@ -164,10 +178,11 @@ export function validateSlug(slug: string): void {
     );
   }
   if (FORBIDDEN_SLUGS.has(slug)) {
-    throw new ProvisionError(
-      2,
-      `Slug "${slug}" is reserved (auto-provisioned per-user, not eligible for cloud promotion)`,
-    );
+    const reason =
+      slug === "personal"
+        ? "auto-provisioned per-user, not eligible for cloud promotion"
+        : "path-traversal slug (would resolve to a directory outside the intended company folder)";
+    throw new ProvisionError(2, `Slug "${slug}" is reserved (${reason})`);
   }
 }
 
@@ -196,6 +211,11 @@ export function companyConfigPath(hqRoot: string, slug: string): string {
  *   - company is `status: archived`
  *   - `companies/<slug>/` does not exist
  *
+ * Strict on purpose — callers that want the "auto-insert a missing entry when
+ * the local folder exists" affordance (cloud-provision's fault-tolerant flow)
+ * MUST call `ensureManifestEntryForProvision` first. cloud-demote and other
+ * sensitive callers depend on this strict failure for typo-catching.
+ *
  * Returns the parsed manifest (so the caller can re-use it for the patch step).
  */
 export function validateManifestAndDir(
@@ -246,6 +266,80 @@ export function validateManifestAndDir(
   return { manifest };
 }
 
+/**
+ * Provision-only pre-step. If `companies/<slug>/` exists on disk but the slug
+ * is absent from `manifest.yaml`, atomically insert an empty entry
+ * (`<slug>: {}`) so the downstream `validateManifestAndDir` + `patchManifest`
+ * flow has something to operate on. Heals the common folder-only state
+ * (manual mkdir, or older tools that didn't patch manifest.yaml) that hq-sync's
+ * Connect button used to dead-end on with exit 2.
+ *
+ * No-op in every other case:
+ *   - manifest file missing / malformed (validation will surface)
+ *   - slug already present (any value, including null — preserved as-is)
+ *   - `companies/<slug>/` does not exist (validation will surface as a typo)
+ *
+ * This affordance is provision-specific. `cloud-demote` and other strict
+ * callers MUST NOT call this — their typo-catching contract depends on
+ * `validateManifestAndDir` throwing on missing-slug.
+ */
+export function ensureManifestEntryForProvision(
+  hqRoot: string,
+  slug: string,
+): void {
+  const mPath = manifestPath(hqRoot);
+  if (!fs.existsSync(mPath)) return;
+  // Defense-in-depth against path-traversal slugs (`.`, `..`, anything that
+  // resolves outside companies/). validateSlug rejects these upstream, but
+  // this helper is exported and might be called directly by future code —
+  // never auto-insert based on a path that isn't a literal direct child of
+  // `companies/`. fs.realpathSync would also catch symlink-escapes, but the
+  // directory may legitimately not exist yet on disk; path.resolve gives us
+  // the canonical lexical form without a stat call.
+  const companiesDir = path.resolve(hqRoot, "companies");
+  const expected = path.resolve(companiesDir, slug);
+  const expectedParent = path.dirname(expected);
+  if (expectedParent !== companiesDir) return;
+  if (path.basename(expected) !== slug) return;
+  const dir = companyDirPath(hqRoot, slug);
+  // Must be an actual directory, not a stray file. fs.existsSync returns true
+  // for regular files too — without this guard, auto-insert would fire on a
+  // file at `companies/<slug>`, provisionCompany would then create the vault
+  // entity and patch manifest.yaml before writeCompanyConfig's `mkdir -p .hq`
+  // exploded with ENOTDIR. statSync swallows the not-found case so a missing
+  // path is treated the same as before (no auto-insert).
+  let dirStat: fs.Stats;
+  try {
+    dirStat = fs.statSync(dir);
+  } catch {
+    return;
+  }
+  if (!dirStat.isDirectory()) return;
+  const raw = fs.readFileSync(mPath, "utf-8");
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(raw);
+  } catch {
+    return;
+  }
+  if (
+    !parsed ||
+    typeof parsed !== "object" ||
+    !("companies" in parsed) ||
+    typeof (parsed as ManifestDoc).companies !== "object"
+  ) {
+    return;
+  }
+  const doc = parsed as ManifestDoc;
+  if (!doc.companies) doc.companies = {};
+  if (doc.companies[slug] !== undefined) return;
+  doc.companies[slug] = {};
+  const dump = yaml.dump(doc, { lineWidth: -1, noRefs: true });
+  const tmp = `${mPath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, dump);
+  fs.renameSync(tmp, mPath);
+}
+
 // ── Manifest patching (atomic) ───────────────────────────────────────────────
 
 /**
@@ -345,6 +439,20 @@ export function createDefaultVaultClient(
     Authorization: `Bearer ${accessToken}`,
   };
   return {
+    async listMyPersonEntities(): Promise<VaultEntity[]> {
+      const url = `${apiUrl.replace(/\/$/, "")}/entity/by-type/person`;
+      const res = await fetch(url, { method: "GET", headers });
+      if (res.status === 404) return [];
+      if (!res.ok) {
+        const body = await safeBody(res);
+        throw new ProvisionError(
+          1,
+          `Vault GET /entity/by-type/person failed: ${res.status} ${res.statusText} — ${body}`,
+        );
+      }
+      const data = (await res.json()) as { entities?: VaultEntity[] };
+      return data.entities ?? [];
+    },
     async findCompanyBySlug(slug: string): Promise<VaultEntity | null> {
       const url = `${apiUrl.replace(/\/$/, "")}/entity/by-slug/company/${encodeURIComponent(
         slug,
@@ -450,8 +558,13 @@ export async function provisionCompany(
 ): Promise<ProvisionResult> {
   const log = options.log ?? ((msg: string) => process.stderr.write(`[hq cloud provision] ${msg}\n`));
 
-  // Step 1+2+3: validate slug, manifest, dir
+  // Step 1+2+3: validate slug, auto-heal a folder-only manifest, then validate
+  // the resulting manifest + dir. The auto-heal is provision-specific: it
+  // inserts an empty entry when companies/<slug>/ exists on disk but the slug
+  // is missing from manifest.yaml. validateManifestAndDir stays strict so
+  // other callers (cloud-demote) keep their typo-catching guard.
   validateSlug(options.slug);
+  ensureManifestEntryForProvision(options.hqRoot, options.slug);
   validateManifestAndDir(options.hqRoot, options.slug);
   log(`validated slug=${options.slug}`);
 
@@ -466,6 +579,27 @@ export async function provisionCompany(
     options.vaultClient ??
     createDefaultVaultClient(options.vaultApiUrl, accessToken);
 
+  // Pre-flight: caller MUST have a registered person entity. Without one,
+  // the initial-sync step at the end of this flow (STS /sts/vend) returns
+  // 403 "no person entity" and leaves the operator with a half-built cloud
+  // company — vault entity created, S3 bucket provisioned, manifest patched,
+  // .hq/config.json written, but nothing actually syncing. This was the
+  // primary failure mode in the 2026-05-14 setup-session deep dive
+  // (Joey Muller / sum-digital).
+  //
+  // Failing here, BEFORE any cloud-side resource creation, leaves the operator
+  // with no cleanup work — they fix the underlying onboarding gap (run
+  // `hq onboard` / sign in with the correct federated identity) and re-run
+  // `hq cloud provision company <slug>` cleanly.
+  const persons = await vaultClient.listMyPersonEntities();
+  if (persons.length === 0) {
+    throw new ProvisionError(
+      2,
+      'No person entity found for this Cognito identity. Run `hq onboard` first to create your HQ identity, then re-run `hq cloud provision company`. (Provision was halted before any cloud-side resources were created.)',
+    );
+  }
+  log(`pre-flight ok — caller has ${persons.length} person entity(ies)`);
+
   let entity = await vaultClient.findCompanyBySlug(options.slug);
   let createdEntity = false;
   if (entity) {