@indigoai-us/hq-cli 5.25.0 → 5.26.0

package/.github/workflows/publish.yml

@@ -80,9 +80,29 @@ jobs:
             echo "published=true" >> "$GITHUB_OUTPUT"
           fi
 
+      # Sentry sourcemap upload runs on every tag push regardless of whether
+      # this run was the one that actually published to npm. The previous
+      # `if: steps.publish.outputs.published == 'true'` gate made re-runs
+      # useless when only the Sentry upload failed — the publish step's
+      # short-circuit (`npm view @ver already published`) zeroed out the
+      # output, so the upload step was skipped on every re-run. dist/ is
+      # rebuilt by the Build + Inject steps each run, so the upload is
+      # always operating on fresh, debug-id-stamped artifacts.
       - name: Upload sourcemaps to Sentry
-        if: steps.publish.outputs.published == 'true'
         run: |
+          # Defang paste-time whitespace in SENTRY_AUTH_TOKEN. Sentry's
+          # auth-header parser returns HTTP 401 "Token string should not
+          # contain spaces" when the secret has a trailing \n or any
+          # embedded whitespace — observed on the v5.25.0 release after a
+          # copy-paste into the GH repo secret carried a literal \n. `tr -d`
+          # is the cheap structural guard so the workflow doesn't blow up
+          # on the next dirty paste.
+          SENTRY_AUTH_TOKEN=$(printf %s "$SENTRY_AUTH_TOKEN" | tr -d '[:space:]')
+          if [ -z "$SENTRY_AUTH_TOKEN" ]; then
+            echo "::error::SENTRY_AUTH_TOKEN secret is empty (or all whitespace) after sanitization — cannot upload sourcemaps"
+            exit 1
+          fi
+          export SENTRY_AUTH_TOKEN
           VER=$(jq -r .version package.json)
           npx -y @sentry/cli@^2 sourcemaps upload --release "hq-cli@$VER" dist/
         env:

package/dist/commands/dm.d.ts

@@ -0,0 +1,41 @@
+import { Command } from "commander";
+export interface DmRecipient {
+    toEmail?: string;
+    toPersonUid?: string;
+}
+/**
+ * Classify a recipient arg as an email or a personUid. Mirrors the
+ * email/prs_ heuristic used by `hq members`. Returns null for neither.
+ */
+export declare function detectRecipient(recipient: string): DmRecipient | null;
+/**
+ * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
+ * Returns null on anything that doesn't match. Pure → unit-testable.
+ */
+export declare function parseDuration(input: string): number | null;
+export interface DmSendBody {
+    toEmail?: string;
+    toPersonUid?: string;
+    body: string;
+    prompt?: string;
+    details?: string;
+    deliverAt?: string;
+}
+/**
+ * Build the POST /v1/notify/dm request body from CLI inputs. Pure (no I/O,
+ * no clock) so the option-resolution logic is unit-testable; the caller
+ * supplies `now` for the `--in` relative-delay computation.
+ *
+ * Throws Error with a user-facing message on invalid input.
+ */
+export declare function buildDmBody(args: {
+    recipient: string;
+    message: string;
+    prompt?: string;
+    details?: string;
+    at?: string;
+    inDelay?: string;
+    now: number;
+}): DmSendBody;
+export declare function registerDmCommand(program: Command): void;
+//# sourceMappingURL=dm.d.ts.map

package/dist/commands/dm.js

@@ -0,0 +1,148 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="69d48194-d5ae-508e-b614-68f2066db6ee")}catch(e){}}();
+import chalk from "chalk";
+import { readFileSync } from "node:fs";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
+const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+/**
+ * Classify a recipient arg as an email or a personUid. Mirrors the
+ * email/prs_ heuristic used by `hq members`. Returns null for neither.
+ */
+export function detectRecipient(recipient) {
+    const r = recipient.trim();
+    if (EMAIL_PATTERN.test(r))
+        return { toEmail: r.toLowerCase() };
+    if (PERSON_UID_PATTERN.test(r))
+        return { toPersonUid: r };
+    return null;
+}
+/**
+ * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
+ * Returns null on anything that doesn't match. Pure → unit-testable.
+ */
+export function parseDuration(input) {
+    const m = /^(\d+)\s*(s|m|h|d)$/.exec(input.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 10);
+    const mult = {
+        s: 1000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+    };
+    return n * mult[m[2]];
+}
+/**
+ * Build the POST /v1/notify/dm request body from CLI inputs. Pure (no I/O,
+ * no clock) so the option-resolution logic is unit-testable; the caller
+ * supplies `now` for the `--in` relative-delay computation.
+ *
+ * Throws Error with a user-facing message on invalid input.
+ */
+export function buildDmBody(args) {
+    const rcpt = detectRecipient(args.recipient);
+    if (!rcpt) {
+        throw new Error(`Invalid recipient '${args.recipient}': must be an email address or a personUid (prs_…).`);
+    }
+    const body = (args.message ?? "").trim();
+    if (!body) {
+        throw new Error("A message body is required: hq dm <recipient> <message>");
+    }
+    if (args.at && args.inDelay) {
+        throw new Error("Use only one of --at or --in, not both.");
+    }
+    let deliverAt;
+    if (args.at) {
+        const when = new Date(args.at);
+        if (isNaN(when.getTime())) {
+            throw new Error(`Invalid --at '${args.at}': must be an ISO8601 date.`);
+        }
+        deliverAt = when.toISOString();
+    }
+    else if (args.inDelay) {
+        const ms = parseDuration(args.inDelay);
+        if (ms === null) {
+            throw new Error(`Invalid --in '${args.inDelay}': use a relative delay like 30s, 10m, 2h, 1d.`);
+        }
+        deliverAt = new Date(args.now + ms).toISOString();
+    }
+    const prompt = args.prompt?.trim();
+    const details = args.details?.trim();
+    return {
+        ...rcpt,
+        body,
+        ...(prompt ? { prompt } : {}),
+        ...(details ? { details } : {}),
+        ...(deliverAt ? { deliverAt } : {}),
+    };
+}
+function friendlyDmError(status, code, fallback) {
+    if (status === 401)
+        return "Not authenticated — run `hq login` and try again.";
+    if (status === 404 || code === "RECIPIENT_NOT_FOUND") {
+        return "Recipient not found or not reachable — you can only DM someone you share an active company with.";
+    }
+    if (status >= 500)
+        return `Server error: ${fallback}`;
+    return fallback;
+}
+export function registerDmCommand(program) {
+    program
+        .command("dm <recipient> [message]")
+        .description("Send a direct message to a teammate (email or personUid). They receive it as an HQ Sync notification.")
+        .option("--prompt <text>", "Agent-context prompt the recipient can one-click copy into their agent")
+        .option("--prompt-file <path>", "Read the agent prompt from a file")
+        .option("--details <text>", "Longer detail shown in the recipient's DM detail window")
+        .option("--details-file <path>", "Read the details from a file")
+        .option("--at <iso>", "Schedule delivery at an ISO8601 time (store-and-forward; delivered within ~60s of the time)")
+        .option("--in <duration>", "Schedule delivery after a relative delay: 30s, 10m, 2h, 1d")
+        .action(async (recipient, message, opts) => {
+        try {
+            // Resolve prompt/details from inline text or a file.
+            let prompt = opts.prompt;
+            if (opts.promptFile)
+                prompt = readFileSync(opts.promptFile, "utf8");
+            let details = opts.details;
+            if (opts.detailsFile)
+                details = readFileSync(opts.detailsFile, "utf8");
+            const reqBody = buildDmBody({
+                recipient,
+                message: message ?? "",
+                prompt,
+                details,
+                at: opts.at,
+                inDelay: opts.in,
+                now: Date.now(),
+            });
+            const token = await ensureCognitoToken();
+            const res = await vaultApiFetch({
+                token,
+                path: "/v1/notify/dm",
+                method: "POST",
+                body: reqBody,
+            });
+            if (!res.ok) {
+                const err = (await res.json().catch(() => ({})));
+                console.error(chalk.red(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText)));
+                process.exit(1);
+            }
+            const data = (await res.json());
+            if (data.scheduled) {
+                console.log(chalk.green(`Scheduled DM to ${recipient} for ${data.deliverAt} (eventId ${data.eventId}).`));
+                console.log(chalk.dim("It delivers within ~60s of that time, even if you're offline."));
+            }
+            else {
+                console.log(chalk.green(`DM sent to ${recipient} (eventId ${data.eventId}).`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=dm.js.map
+//# debugId=69d48194-d5ae-508e-b614-68f2066db6ee

package/dist/commands/pkg-install.js

@@ -13,7 +13,7 @@
  * 9. Print next-step message
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="874fe8a4-2348-5f03-8600-c545cac13fc9")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c6ab4668-f147-5612-bbfc-e1e80b2f018a")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -21,7 +21,7 @@ import * as yaml from 'js-yaml';
 import { execSync } from 'child_process';
 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, } from '../utils/registry-client.js';
 import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
 import { addToRegistry } from '../utils/registry.js';
@@ -93,7 +93,7 @@ async function installPackage(slug, company) {
             }
         }
         // 7. Extract
-        const hqRoot = findHqRoot();
+        const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
         const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
         // Clean existing installation
         if (fs.existsSync(installDir)) {
@@ -156,4 +156,4 @@ async function installPackage(slug, company) {
     }
 }
 //# sourceMappingURL=pkg-install.js.map
-//# debugId=874fe8a4-2348-5f03-8600-c545cac13fc9
+//# debugId=c6ab4668-f147-5612-bbfc-e1e80b2f018a

package/dist/commands/pkg-list.js

@@ -4,9 +4,9 @@
  * Graceful offline: if registry is unreachable, show cached data with a note.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ce4886ce-109a-5ace-b8d9-4e5bed61978a")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2ca922cd-1115-5059-850d-3927226eb9ee")}catch(e){}}();
 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 { getRegistryUrl, RegistryClient, } from '../utils/registry-client.js';
@@ -26,7 +26,7 @@ export function registerPackageListCommand(parent) {
     });
 }
 async function listPackages() {
-    const hqRoot = findHqRoot();
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const installed = readRegistry(hqRoot);
     // Print installed packages
     if (installed.length > 0) {
@@ -70,4 +70,4 @@ async function listPackages() {
     }
 }
 //# sourceMappingURL=pkg-list.js.map
-//# debugId=ce4886ce-109a-5ace-b8d9-4e5bed61978a
+//# debugId=2ca922cd-1115-5059-850d-3927226eb9ee

package/dist/commands/pkg-remove.js

@@ -6,11 +6,11 @@
  * 3. Print next-step message
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b54529d6-de12-595e-b1c7-ab50b9f22eb5")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e44da498-3e38-5643-b124-49aa2e91f42b")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 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) {
     parent
@@ -27,7 +27,7 @@ export function registerPackageRemoveCommand(parent) {
     });
 }
 async function removePackage(slug) {
-    const hqRoot = findHqRoot();
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
     // Verify it is actually installed
     const entries = readRegistry(hqRoot);
@@ -53,4 +53,4 @@ async function removePackage(slug) {
     console.log(chalk.cyan('Run /package-remove ' + slug + ' in Claude to clean up merged content.'));
 }
 //# sourceMappingURL=pkg-remove.js.map
-//# debugId=b54529d6-de12-595e-b1c7-ab50b9f22eb5
+//# debugId=e44da498-3e38-5643-b124-49aa2e91f42b

package/dist/commands/pkg-update.js

@@ -5,7 +5,7 @@
  * If slug given: update only that package.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3ef2968d-eb65-594b-a506-4314b70dd3dc")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="35fae6a0-f8e1-5fde-90d8-34ae4adb3c1c")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -13,7 +13,7 @@ import * as yaml from 'js-yaml';
 import { execSync } from 'child_process';
 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, } from '../utils/registry-client.js';
 import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
 import { readRegistry, addToRegistry, } from '../utils/registry.js';
@@ -32,7 +32,7 @@ export function registerPackageUpdateCommand(parent) {
     });
 }
 async function updatePackages(slug) {
-    const hqRoot = findHqRoot();
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const entries = readRegistry(hqRoot);
     if (entries.length === 0) {
         console.log('No packages installed. Use "hq packages install <slug>" to install one.');
@@ -124,4 +124,4 @@ async function updatePackages(slug) {
     console.log(`\n${updatedCount} package(s) updated${updatedCount > 0 ? '.' : ' — everything is current.'}`);
 }
 //# sourceMappingURL=pkg-update.js.map
-//# debugId=3ef2968d-eb65-594b-a506-4314b70dd3dc
+//# debugId=35fae6a0-f8e1-5fde-90d8-34ae4adb3c1c

package/dist/commands/team-sync.js

@@ -10,13 +10,13 @@
  * 6. Gracefully handle conflicts (warn, don't force overwrite)
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4c9a650e-05ed-5e33-b5de-b6d521ecdf4f")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2b2504c1-06d5-59f8-a9b3-41d1af7f745f")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 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';
 // ─── API helpers ────────────────────────────────────────────────────────────
 const API_BASE = 'https://example.com/api';
@@ -308,7 +308,7 @@ export function registerTeamSyncCommand(program) {
         .option('--dry-run', 'Show what would be synced without making changes')
         .action(async (options) => {
         try {
-            const hqRoot = findHqRoot();
+            const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
             // 1. Discover team directories
             let teamDirs = discoverTeamDirs(hqRoot);
             if (teamDirs.length === 0) {
@@ -422,4 +422,4 @@ export function registerTeamSyncCommand(program) {
     });
 }
 //# sourceMappingURL=team-sync.js.map
-//# debugId=4c9a650e-05ed-5e33-b5de-b6d521ecdf4f
+//# debugId=2b2504c1-06d5-59f8-a9b3-41d1af7f745f

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a9b69c08-39a6-58c3-a4b6-a309d0ab8254")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d7693093-4011-58fa-b5be-805b5f9f5421")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -31,12 +31,14 @@ import { registerGroupsCommand } from "./commands/groups.js";
 import { registerFilesCommand } from "./commands/files.js";
 import { registerFilesBrowseCommands } from "./commands/files-browse.js";
 import { registerMembersCommand } from "./commands/members.js";
+import { registerDmCommand } from "./commands/dm.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
 import { registerMeetingsCommand } from "./commands/meetings.js";
 import { registerSourcesCommand } from "./commands/sources.js";
 import { registerSignalsCommand } from "./commands/signals.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 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.
 const onPipeError = (err) => {
@@ -109,6 +111,7 @@ const filesCmd = registerFilesCommand(program);
 registerFilesBrowseCommands(filesCmd);
 // Membership management (subcommand group — hq members invite|list|revoke)
 registerMembersCommand(program);
+registerDmCommand(program);
 // Onboarding (top-level — Cognito + vault-service provisioning)
 registerOnboardCommand(program);
 // Feedback (subcommand group — hq feedback bug|feature)
@@ -126,6 +129,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) {
@@ -137,4 +148,4 @@ registerSignalsCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=a9b69c08-39a6-58c3-a4b6-a309d0ab8254
+//# debugId=d7693093-4011-58fa-b5be-805b5f9f5421

package/dist/utils/cognito-session.d.ts

@@ -45,7 +45,28 @@ export declare const DEFAULT_VAULT_API_URL: string;
  * 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 declare 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 declare function resolveDefaultHqRoot(opts?: {
+    onMissing?: "throw" | "fallback";
+}): string;
 export declare const DEFAULT_HQ_ROOT: string;
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in

package/dist/utils/cognito-session.js

@@ -19,7 +19,7 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d16ef3c7-eead-5307-aaa7-ca5fc828102b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cd9690e0-c7b0-5e26-a3ee-7f7bc98a0fe2")}catch(e){}}();
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -67,7 +67,26 @@ export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hq
  * 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() {
+/**
+ * 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 = {}) {
     if (process.env.HQ_ROOT)
         return path.resolve(process.env.HQ_ROOT);
     let cur = path.resolve(process.cwd());
@@ -76,6 +95,10 @@ export function resolveDefaultHqRoot() {
             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");
 }
 /** True iff `dir` looks like an HQ root (has core.yaml + companies/ dir). */
@@ -170,4 +193,4 @@ export async function refreshCachedSession() {
     }
 }
 //# sourceMappingURL=cognito-session.js.map
-//# debugId=d16ef3c7-eead-5307-aaa7-ca5fc828102b
+//# debugId=cd9690e0-c7b0-5e26-a3ee-7f7bc98a0fe2

package/dist/utils/integrity.js

@@ -2,11 +2,11 @@
  * Integrity verification — SHA256 hash and RSA signature checks (US-005)
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="19765c32-6c3d-5477-bf80-0f7d08197d29")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="820f12b3-4caf-5f08-9add-621628715744")}catch(e){}}();
 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.
  */
@@ -29,7 +29,7 @@ export async function verifySha256(filePath, expectedHash) {
  */
 export function verifyRsaSignature(sha256Hash, signature, publicKeyPath) {
     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;
     }
@@ -40,4 +40,4 @@ export function verifyRsaSignature(sha256Hash, signature, publicKeyPath) {
     return verifier.verify(publicKey, Buffer.from(signature, 'base64'));
 }
 //# sourceMappingURL=integrity.js.map
-//# debugId=19765c32-6c3d-5477-bf80-0f7d08197d29
+//# debugId=820f12b3-4caf-5f08-9add-621628715744

package/dist/utils/registry-client.js

@@ -5,11 +5,11 @@
  * Auth tokens are NEVER written to stdout or logs.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ffe2dc58-fb20-5566-a56c-1b1c26999bba")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="43d1600f-1bf7-5a52-819b-83e71ba30c73")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
-import { findHqRoot } from './hq-root.js';
+import { resolveDefaultHqRoot } from './cognito-session.js';
 // ---------------------------------------------------------------------------
 // URL helper (unchanged from US-004)
 // ---------------------------------------------------------------------------
@@ -19,7 +19,7 @@ import { findHqRoot } from './hq-root.js';
  * Throws if sources.yaml is missing or has no sources.
  */
 export function getRegistryUrl() {
-    const hqRoot = findHqRoot();
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const sourcesPath = path.join(hqRoot, 'packages', 'sources.yaml');
     if (!fs.existsSync(sourcesPath)) {
         throw new Error(`No packages/sources.yaml found at ${sourcesPath}. Is your HQ packages directory set up?`);
@@ -102,4 +102,4 @@ export class RegistryClient {
     }
 }
 //# sourceMappingURL=registry-client.js.map
-//# debugId=ffe2dc58-fb20-5566-a56c-1b1c26999bba
+//# debugId=43d1600f-1bf7-5a52-819b-83e71ba30c73

package/dist/utils/version-gate.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Hard version-gate: ask hq-pro whether the current CLI is below the minimum
+ * acceptable version and, if so, run `npm install -g …@latest` synchronously
+ * before any commander parsing happens. Distinct from the existing
+ * `version-check.ts` which is a passive (cached, opt-in) stderr nag against
+ * the npm registry.
+ *
+ * Why both?
+ *   - `version-check.ts` answers "is there something newer?" by polling npm
+ *     directly. It's a soft hint, lives on a 24h cache, and never blocks.
+ *   - `version-gate.ts` answers "is the team currently allowing your version
+ *     to run?" via an authoritative hq-pro endpoint. The server can yank a
+ *     known-bad release without waiting for the npm `latest` dist-tag move.
+ *
+ * The endpoint is reusable across clients (hq-sync, hq-installer, create-hq).
+ * See `apps/hq-pro/src/vault-service/handlers/client-version-check.ts` for the
+ * source-of-truth table.
+ *
+ * Trust model: anonymous. The CLI may be running pre-login (e.g. fresh
+ * install) so we never send credentials. The endpoint identifies the client
+ * by `clientId` + `currentVersion`.
+ *
+ * Failure mode: silent. Network down, hq-pro returning 5xx, malformed body —
+ * the gate must never break the CLI for a user who's otherwise fine. We log
+ * to Sentry as a breadcrumb (best-effort) and return.
+ *
+ * Opt-out: `HQ_NO_UPDATE_CHECK=1` (same env as `version-check.ts` — one knob
+ * to silence both check + gate).
+ */
+/**
+ * Run the upgrade command in a blocking subprocess. Inherits stdio so the
+ * user sees the npm progress. We do NOT auto-rerun the CLI on completion —
+ * forcing a re-invocation would run twice on the same process and feel
+ * janky; instead we print a clear "rerun your command" message and exit.
+ */
+declare function performUpdate(command: string): {
+    ok: boolean;
+    detail?: string;
+};
+/**
+ * Public entry point. Call before commander parses argv. Blocks the CLI on
+ * network IO for up to FETCH_TIMEOUT_MS — acceptable because the alternative
+ * (a fire-and-forget background check) gives the user no chance to bail out
+ * of a known-bad version before it does damage.
+ *
+ * `--version` / `-v` callers MUST skip the gate (the user is debugging a
+ * broken install and shouldn't be force-upgraded mid-investigation). Caller
+ * is responsible for checking argv before invoking us — see index.ts.
+ */
+export declare function enforceVersionGate(): Promise<void>;
+/**
+ * Cheap argv pre-check: skip the gate for `--version` / `-V` so users
+ * inspecting a broken install can still see what they have without being
+ * force-upgraded.
+ */
+export declare function shouldSkipGate(argv: readonly string[]): boolean;
+export declare const __test__: {
+    CLIENT_ID: string;
+    ENDPOINT_PATH: string;
+    FETCH_TIMEOUT_MS: number;
+    performUpdate: typeof performUpdate;
+};
+export {};
+//# sourceMappingURL=version-gate.d.ts.map