@indigoai-us/hq-cli 5.24.0 → 5.25.1

package/src/commands/members.ts

@@ -33,6 +33,17 @@ export interface InviteOptions {
   target: string;
   role: string;
   paths?: string;
+  /** Email-keyed invites only — secret-group ids to attach on claim. */
+  groupIds?: string[];
+  /**
+   * Opt the server-side Resend send in/out. When `true`, hq-pro renders +
+   * sends the invitation email server-side and returns `emailSent` /
+   * `emailSkipped` / `emailError`. When `false` or unset, the legacy
+   * no-email path runs and the CLI prints the manual sign-in instructions.
+   * Requires hq-pro that supports `sendEmail` (older servers ignore the
+   * field; CLI falls back to the legacy printout in that case).
+   */
+  sendEmail?: boolean;
   companyUid: string;
   callerUid: string;
   token: string;
@@ -51,6 +62,10 @@ export interface InviteOptions {
  *    instructions instead.
  *
  * `membership` is always populated when the server returned 2xx.
+ *
+ * Email-related fields are populated only when hq-pro performed a
+ * server-side Resend send (caller passed `sendEmail: true` AND the
+ * server supports it). Pre-resend servers omit them entirely.
  */
 export interface InviteResult {
   inviteToken?: string;
@@ -62,6 +77,31 @@ export interface InviteResult {
     inviteToken?: string;
     inviteeEmail?: string;
   };
+  /** Resend send actually fired and accepted by Resend. */
+  emailSent?: boolean;
+  /** Resend skipped because the server has no RESEND_API_KEY configured. */
+  emailSkipped?: boolean;
+  /** Resend was attempted but failed — human-readable reason. */
+  emailError?: string;
+}
+
+export interface ResendInviteOptions {
+  inviteeEmail: string;
+  companyUid: string;
+  callerUid: string;
+  token: string;
+}
+
+/**
+ * Outcome of `hq members invite --resend`. No new membership row was
+ * created — the server's `resend: true` short-circuit just re-fires the
+ * Resend email against the existing pending row.
+ */
+export interface ResendInviteResult {
+  resent: true;
+  emailSent: boolean;
+  emailSkipped: boolean;
+  emailError?: string;
 }
 
 export interface DetectedTarget {
@@ -127,6 +167,12 @@ export async function inviteMember(
     );
   }
 
+  if (options.groupIds && options.groupIds.length > 0 && detected.type === "person") {
+    throw new Error(
+      "--groups is only valid on email-keyed invites (server rejects personUid + groupIds with 400)",
+    );
+  }
+
   const allowedPrefixes = options.paths
     ? options.paths.split(",").map((p) => p.trim()).filter(Boolean)
     : undefined;
@@ -139,6 +185,10 @@ export async function inviteMember(
   if (detected.type === "email") body.inviteeEmail = detected.value;
   else body.personUid = detected.value;
   if (allowedPrefixes) body.allowedPrefixes = allowedPrefixes;
+  if (options.groupIds && options.groupIds.length > 0) {
+    body.groupIds = options.groupIds;
+  }
+  if (options.sendEmail === true) body.sendEmail = true;
 
   const res = await vaultApiFetch({
     token: options.token,
@@ -166,6 +216,9 @@ export async function inviteMember(
       schemaVersion?: number;
     };
     inviteToken?: string;
+    emailSent?: boolean;
+    emailSkipped?: boolean;
+    emailError?: string;
   };
   if (!data.membership) {
     const keys = Object.keys(data ?? {}).join(", ") || "<empty>";
@@ -189,6 +242,77 @@ export async function inviteMember(
       ? { inviteToken, magicLink: `hq://accept/${inviteToken}` }
       : {}),
     membership: data.membership,
+    // Pre-resend hq-pro versions omit these fields entirely — leave the
+    // result fields undefined so the caller's "is server-side email
+    // supported?" check works via `typeof result.emailSent === 'boolean'`.
+    ...(typeof data.emailSent === "boolean" ? { emailSent: data.emailSent } : {}),
+    ...(typeof data.emailSkipped === "boolean"
+      ? { emailSkipped: data.emailSkipped }
+      : {}),
+    ...(data.emailError ? { emailError: data.emailError } : {}),
+  };
+}
+
+/**
+ * Re-fire the invite email against an existing pending row without
+ * creating a new membership row. Maps to hq-pro `/membership/invite`
+ * with `{ resend: true }` (see hq-pro PR #140). Server gates on the
+ * caller's admin/owner role.
+ *
+ * Returns the email-send status. 404 here means "no pending row exists
+ * for this email+company pair — re-invite without --resend first."
+ */
+export async function resendInvite(
+  options: ResendInviteOptions,
+): Promise<ResendInviteResult> {
+  const detected = detectTarget(options.inviteeEmail);
+  if (!detected || detected.type !== "email") {
+    throw new Error(
+      "--resend requires an email target (the resend path is email-keyed-row only)",
+    );
+  }
+
+  const res = await vaultApiFetch({
+    token: options.token,
+    path: "/membership/invite",
+    method: "POST",
+    body: {
+      companyUid: options.companyUid,
+      // Server's invite handler still requires `role` even on the resend
+      // short-circuit. Pass the safe default — server ignores it on this
+      // path (the pending row already has its real role).
+      role: "member",
+      inviteeEmail: detected.value,
+      invitedBy: options.callerUid,
+      resend: true,
+    },
+  });
+
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new InviteHttpError(
+      res.status,
+      err.message ?? err.error ?? res.statusText,
+      err.code,
+    );
+  }
+
+  const data = (await res.json()) as {
+    resent?: boolean;
+    emailSent?: boolean;
+    emailSkipped?: boolean;
+    emailError?: string;
+  };
+  if (data.resent !== true) {
+    throw new Error(
+      "Resend endpoint returned 2xx without `resent: true` — the connected hq-pro likely doesn't support `resend: true` yet. Upgrade hq-pro or re-invite without --resend.",
+    );
+  }
+  return {
+    resent: true,
+    emailSent: data.emailSent === true,
+    emailSkipped: data.emailSkipped === true,
+    ...(data.emailError ? { emailError: data.emailError } : {}),
   };
 }
 
@@ -279,6 +403,37 @@ export function resolveRevokeTargetToMembershipKey(
   return arg;
 }
 
+function printEmailStatus(opts: {
+  recipient: string;
+  sent: boolean;
+  skipped: boolean;
+  error?: string;
+}): void {
+  if (opts.sent) {
+    console.log(
+      chalk.green(`✓ Invitation email sent to ${opts.recipient.toLowerCase()}`),
+    );
+    return;
+  }
+  if (opts.skipped) {
+    console.log(
+      chalk.yellow(
+        `⚠ Email send skipped — hq-pro has no RESEND_API_KEY configured for this stage.`,
+      ),
+    );
+    return;
+  }
+  if (opts.error) {
+    console.log(chalk.yellow(`⚠ Email send failed: ${opts.error}`));
+    return;
+  }
+  console.log(
+    chalk.yellow(
+      `⚠ Email status unknown — hq-pro returned no email fields (likely a pre-resend deploy).`,
+    ),
+  );
+}
+
 export async function revokeInvite(
   token: string,
   tokenOrKey: string,
@@ -309,7 +464,7 @@ export function registerMembersCommand(program: Command): void {
   members
     .command("invite <target>")
     .description(
-      "Invite a person to the company by email or personUid (prints a magic link)",
+      "Invite a person to the company by email or personUid (sends an invitation email by default)",
     )
     .option(
       "--role <role>",
@@ -320,10 +475,33 @@ export function registerMembersCommand(program: Command): void {
       "--paths <prefixes>",
       "Comma-separated allowed prefixes (only valid with --role guest)",
     )
+    .option(
+      "--groups <ids>",
+      "Comma-separated secret-group ids the invitee will be added to on claim (email-keyed invites only)",
+    )
+    .option(
+      "--send-email",
+      "Have hq-pro send an invitation email via Resend (default true for email-keyed invites). Pre-resend hq-pro versions ignore this and the legacy 'no email sent' instructions print instead.",
+      true,
+    )
+    .option(
+      "--no-send-email",
+      "Skip the server-side Resend send — only create the pending DDB row. Useful when you're scripting bulk invites and will send the announcement out-of-band.",
+    )
+    .option(
+      "--resend",
+      "Re-fire the invitation email against an existing pending row without creating a new row. Maps to hq-pro `resend: true` short-circuit. Email-keyed invites only.",
+    )
     .action(
       async (
         target: string,
-        opts: { role: string; paths?: string },
+        opts: {
+          role: string;
+          paths?: string;
+          groups?: string;
+          sendEmail: boolean;
+          resend?: boolean;
+        },
       ) => {
         try {
           const token = await ensureCognitoToken();
@@ -331,10 +509,39 @@ export function registerMembersCommand(program: Command): void {
           const companyUid = await getCompanyUid(token, companySlug);
           const callerUid = await getCallerPersonUid(token);
 
+          // --resend short-circuits to the server's re-fire path. No new row.
+          if (opts.resend === true) {
+            const resendResult = await resendInvite({
+              inviteeEmail: target,
+              companyUid,
+              callerUid,
+              token,
+            });
+            console.log(
+              chalk.green(
+                `Re-fired invite email for ${target.toLowerCase()} (existing pending row left untouched)`,
+              ),
+            );
+            console.log();
+            printEmailStatus({
+              recipient: target,
+              sent: resendResult.emailSent,
+              skipped: resendResult.emailSkipped,
+              error: resendResult.emailError,
+            });
+            return;
+          }
+
+          const groupIds = opts.groups
+            ? opts.groups.split(",").map((g) => g.trim()).filter(Boolean)
+            : undefined;
+
           const result = await inviteMember({
             target,
             role: opts.role,
             paths: opts.paths,
+            groupIds,
+            sendEmail: opts.sendEmail,
             companyUid,
             callerUid,
             token,
@@ -356,52 +563,91 @@ export function registerMembersCommand(program: Command): void {
                 "Share this link with the invitee. They can run `hq onboard join --invite-token <token>` to accept.",
               ),
             );
-          } else {
-            // schemaVersion 2+ — email-keyed authoritative membership row.
-            // No magic link to share; invitee accepts by signing into HQ.
-            //
-            // CRITICAL UX NOTE: this CLI command does NOT send any email.
-            // hq-pro only writes the DDB pending row; only the hq-console UI
-            // path triggers Resend. Operators who run `hq members invite`
-            // expecting an email to fly out get silently broken flows. The
-            // output below uses chalk.yellow + an explicit "no email sent"
-            // line so this never sneaks past again.
-            const inviteeEmail =
-              result.membership.inviteeEmail ??
-              (typeof target === "string" && target.includes("@")
-                ? target
-                : undefined);
+            return;
+          }
+
+          // schemaVersion 2+ — email-keyed authoritative membership row.
+          // Three output branches depending on whether the server-side
+          // Resend send fired:
+          //   (a) emailSent === true  → "email sent" success line
+          //   (b) emailSkipped === true → server has no RESEND_API_KEY;
+          //       fall back to the manual-notify instructions
+          //   (c) emailSent/emailSkipped both undefined → pre-resend
+          //       hq-pro, doesn't understand `sendEmail` at all; fall
+          //       back to the manual-notify instructions
+          const inviteeEmail =
+            result.membership.inviteeEmail ??
+            (typeof target === "string" && target.includes("@")
+              ? target
+              : undefined);
+          const emailDelivered = result.emailSent === true;
+          if (emailDelivered) {
+            printEmailStatus({
+              recipient: inviteeEmail ?? target,
+              sent: true,
+              skipped: false,
+              error: undefined,
+            });
+            if (result.membership.membershipKey) {
+              console.log();
+              console.log(
+                chalk.dim(`Membership key: ${result.membership.membershipKey}`),
+              );
+            }
+            return;
+          }
+          // Email-send failed or wasn't attempted — surface the manual path.
+          if (result.emailError) {
             console.log(
-              chalk.yellow(
-                "⚠ No email was sent. `hq members invite` only creates the pending membership row.",
-              ),
+              chalk.yellow(`⚠ Email send failed: ${result.emailError}`),
             );
             console.log();
-            console.log(chalk.bold("To complete the invite, do ONE of:"));
-            console.log(
-              `  1. Manually notify ${inviteeEmail ?? "the invitee"}: ask them to sign into HQ`,
-            );
-            console.log(
-              `     at https://hq.getindigo.ai with that email address.`,
-            );
-            console.log(
-              `  2. Or use the hq-console UI at https://hq.getindigo.ai to issue the`,
-            );
+          }
+          console.log(
+            chalk.yellow(
+              "⚠ No email was sent. The pending membership row exists; the invitee needs to sign in manually to claim it.",
+            ),
+          );
+          console.log();
+          console.log(chalk.bold("To complete the invite, do ONE of:"));
+          console.log(
+            `  1. Manually notify ${inviteeEmail ?? "the invitee"}: ask them to sign into HQ`,
+          );
+          console.log(
+            `     at https://hq.getindigo.ai with that email address.`,
+          );
+          console.log(
+            `  2. Or use the hq-console UI at https://hq.getindigo.ai to issue the`,
+          );
+          console.log(
+            `     invite instead — the UI path triggers an automated email via Resend.`,
+          );
+          if (result.emailSkipped !== true && result.emailSent === undefined) {
+            console.log();
             console.log(
-              `     invite instead — the UI path triggers an automated email via Resend.`,
+              chalk.dim(
+                "Tip: this hq-pro deploy doesn't support server-side email yet (`sendEmail` ignored). Ask an operator to ship hq-pro PR #140 + provision the ResendApiKey SST secret.",
+              ),
             );
+          } else if (result.emailSkipped === true) {
             console.log();
             console.log(
               chalk.dim(
-                "The pending membership row claims itself on the invitee's first sign-in.",
+                "Tip: hq-pro reported `emailSkipped: true` — its `RESEND_API_KEY` SST secret isn't set for this stage.",
               ),
             );
-            if (result.membership.membershipKey) {
-              console.log();
-              console.log(
-                chalk.dim(`Membership key: ${result.membership.membershipKey}`),
-              );
-            }
+          }
+          console.log();
+          console.log(
+            chalk.dim(
+              "The pending membership row claims itself on the invitee's first sign-in.",
+            ),
+          );
+          if (result.membership.membershipKey) {
+            console.log();
+            console.log(
+              chalk.dim(`Membership key: ${result.membership.membershipKey}`),
+            );
           }
         } catch (err) {
           if (err instanceof InviteHttpError) {

package/src/commands/pkg-install.ts

@@ -21,7 +21,7 @@ import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
-import { findHqRoot } from '../utils/hq-root.js';
+import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import {
   getRegistryUrl,
   RegistryClient,
@@ -124,7 +124,7 @@ async function installPackage(
     }
 
     // 7. Extract
-    const hqRoot = findHqRoot();
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
 
     // Clean existing installation

package/src/commands/pkg-list.ts

@@ -6,7 +6,7 @@
 
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { findHqRoot } from '../utils/hq-root.js';
+import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import { readRegistry } from '../utils/registry.js';
 import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
 import {
@@ -34,7 +34,7 @@ export function registerPackageListCommand(parent: Command): void {
 }
 
 async function listPackages(): Promise<void> {
-  const hqRoot = findHqRoot();
+  const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
   const installed = readRegistry(hqRoot);
 
   // Print installed packages

package/src/commands/pkg-remove.ts

@@ -10,7 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { findHqRoot } from '../utils/hq-root.js';
+import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import { removeFromRegistry, readRegistry } from '../utils/registry.js';
 
 export function registerPackageRemoveCommand(parent: Command): void {
@@ -31,7 +31,7 @@ export function registerPackageRemoveCommand(parent: Command): void {
 }
 
 async function removePackage(slug: string): Promise<void> {
-  const hqRoot = findHqRoot();
+  const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
   const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
 
   // Verify it is actually installed

package/src/commands/pkg-update.ts

@@ -13,7 +13,7 @@ import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
-import { findHqRoot } from '../utils/hq-root.js';
+import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import {
   getRegistryUrl,
   RegistryClient,
@@ -43,7 +43,7 @@ export function registerPackageUpdateCommand(parent: Command): void {
 }
 
 async function updatePackages(slug?: string): Promise<void> {
-  const hqRoot = findHqRoot();
+  const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
   const entries = readRegistry(hqRoot);
 
   if (entries.length === 0) {

package/src/commands/team-sync.ts

@@ -16,7 +16,7 @@ import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import simpleGit from 'simple-git';
-import { findHqRoot } from '../utils/hq-root.js';
+import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
@@ -433,7 +433,7 @@ export function registerTeamSyncCommand(program: Command): void {
     .action(
       async (options: { team?: string; dryRun?: boolean }) => {
         try {
-          const hqRoot = findHqRoot();
+          const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
 
           // 1. Discover team directories
           let teamDirs = discoverTeamDirs(hqRoot);

package/src/index.ts

@@ -40,6 +40,10 @@ import {
   maybeWarnNewVersion,
   refreshVersionCache,
 } from "./utils/version-check.js";
+import {
+  enforceVersionGate,
+  shouldSkipGate,
+} from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
 
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes the pipe early.
@@ -157,6 +161,14 @@ registerSignalsCommand(program);
       message: sanitizeArgv(process.argv.slice(2)).join(" "),
       level: "info",
     });
+    // Hard version gate: ask hq-pro whether this CLI is below the floor and
+    // auto-update if so (exits the process on update). Skipped for inspection
+    // flags (`--version`, `--help`) so users debugging a broken install can
+    // still introspect what they have. Silent on any failure — never blocks
+    // the CLI on a flaky network or hq-pro hiccup. See `utils/version-gate.ts`.
+    if (!shouldSkipGate(process.argv)) {
+      await enforceVersionGate();
+    }
     await program.parseAsync();
   } catch (err) {
     Sentry.captureException(err);

package/src/utils/cognito-session.test.ts

@@ -4,7 +4,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -114,6 +114,61 @@ describe("resolveDefaultHqRoot", () => {
 
     expect(resolveDefaultHqRoot()).toBe(explicit);
   });
+
+  // ── onMissing: throw vs fallback ──────────────────────────────────────
+  //
+  // Default behavior (no opts) is fallback to ~/hq — preserves the
+  // pre-dedup module-load contract of `DEFAULT_HQ_ROOT = resolveDefaultHqRoot()`.
+  // Module-management commands (pkg-*, team-sync) opt into throw mode so a
+  // user invoking the command from outside an HQ gets a clear error instead
+  // of a silent default-path miss.
+  it("onMissing: 'throw' throws when no HQ root is found above cwd", () => {
+    const stranded = join(tmpRoot, "stranded");
+    mkdirSync(stranded, { recursive: true });
+    process.chdir(stranded);
+
+    expect(() => resolveDefaultHqRoot({ onMissing: "throw" })).toThrow(
+      /Could not find HQ root/i,
+    );
+  });
+
+  it("onMissing: 'throw' still honors $HQ_ROOT even though dir wouldn't otherwise be detected", () => {
+    // HQ_ROOT is treated as an explicit assertion by the caller — no
+    // walk-and-throw applies. Module-management commands run with
+    // HQ_ROOT=/abs/path should succeed regardless of cwd.
+    const explicit = join(tmpRoot, "explicit");
+    mkdirSync(explicit, { recursive: true });
+    process.env.HQ_ROOT = explicit;
+    process.chdir(tmpRoot);
+
+    expect(resolveDefaultHqRoot({ onMissing: "throw" })).toBe(explicit);
+  });
+
+  it("onMissing: 'throw' still resolves when cwd IS an HQ root", () => {
+    const hqDir = join(tmpRoot, "hq");
+    mkdirSync(join(hqDir, "companies"), { recursive: true });
+    writeFileSync(join(hqDir, "core.yaml"), "version: 14.1.1\n");
+
+    process.chdir(hqDir);
+    // realpath both sides: macOS /tmp -> /private/var/folders symlink would
+    // otherwise produce a spurious mismatch (same root cause as the two
+    // pre-existing failing `priority 2:` tests above).
+    expect(realpathSync(resolveDefaultHqRoot({ onMissing: "throw" }))).toBe(
+      realpathSync(hqDir),
+    );
+  });
+
+  it("default (no opts) falls back to ~/hq — back-compat with module-load DEFAULT_HQ_ROOT", () => {
+    // Regression pin: any code that imports `DEFAULT_HQ_ROOT` (resolved at
+    // module load) MUST NOT throw if the loader's cwd is outside an HQ.
+    // This contract pre-dates the onMissing parameter and several commands
+    // depend on it (commander.js .option() registration time).
+    const stranded = join(tmpRoot, "stranded");
+    mkdirSync(stranded, { recursive: true });
+    process.chdir(stranded);
+
+    expect(() => resolveDefaultHqRoot()).not.toThrow();
+  });
 });
 
 describe("CLI_CLIENT_INFO + buildVaultConfig", () => {

package/src/utils/cognito-session.ts

@@ -80,13 +80,40 @@ export const DEFAULT_VAULT_API_URL =
  * value at registration time, which matches the user's actual cwd at process
  * start. Re-importable as a function for tests and command-time resolution.
  */
-export function resolveDefaultHqRoot(): string {
+/**
+ * Resolve the HQ root directory.
+ *
+ * Resolution order:
+ *   1. $HQ_ROOT env var (treated as an explicit assertion by the caller)
+ *   2. Walk up from cwd looking for `core.yaml` AND `companies/` siblings
+ *   3. Fall back to `~/hq` (or throw, per `opts.onMissing`)
+ *
+ * `opts.onMissing` controls the third arm:
+ *   - `'fallback'` (default) — return `~/hq` if no HQ root is found above cwd.
+ *     This preserves the module-load contract of `DEFAULT_HQ_ROOT`, which
+ *     several commander.js `.option()` callers pin at registration time.
+ *   - `'throw'` — throw with a user-actionable error. Used by module-management
+ *     commands (pkg-install, pkg-remove, pkg-list, pkg-update, team-sync) where
+ *     a silent default-path miss would silently target the wrong directory.
+ *
+ * `$HQ_ROOT` short-circuits both arms — if the env var is set, it's used
+ * as-is regardless of `onMissing`.
+ */
+export function resolveDefaultHqRoot(opts: {
+  onMissing?: "throw" | "fallback";
+} = {}): string {
   if (process.env.HQ_ROOT) return path.resolve(process.env.HQ_ROOT);
   let cur = path.resolve(process.cwd());
   while (cur !== path.dirname(cur)) {
     if (isHqRoot(cur)) return cur;
     cur = path.dirname(cur);
   }
+  if (opts.onMissing === "throw") {
+    throw new Error(
+      "Could not find HQ root. Run this command from within your HQ directory " +
+        "(must contain core.yaml AND a companies/ subdirectory), or set $HQ_ROOT.",
+    );
+  }
   return path.join(os.homedir(), "hq");
 }
 

package/src/utils/integrity.ts

@@ -5,7 +5,7 @@
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { findHqRoot } from './hq-root.js';
+import { resolveDefaultHqRoot } from './cognito-session.js';
 
 /**
  * Verify a file's SHA256 hash matches the expected value.
@@ -39,7 +39,7 @@ export function verifyRsaSignature(
 ): boolean {
   const keyPath =
     publicKeyPath ??
-    path.resolve(findHqRoot(), 'packages', '.keys', 'registry-public.pem');
+    path.resolve(resolveDefaultHqRoot({ onMissing: 'throw' }), 'packages', '.keys', 'registry-public.pem');
 
   if (!fs.existsSync(keyPath)) {
     return false;