@indigoai-us/hq-cli 5.50.1 → 5.50.2

package/dist/commands/onboard-warning.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Builds the static create-time warning surfaced by both `create-company` and
+ * `dry-run`, because users may accidentally create duplicate companies instead
+ * of joining the existing company they were invited to.
+ */
+export declare function buildCreateCompanyWarning(): string;
+//# sourceMappingURL=onboard-warning.d.ts.map

package/dist/commands/onboard-warning.js

@@ -0,0 +1,14 @@
+/**
+ * Builds the static create-time warning surfaced by both `create-company` and
+ * `dry-run`, because users may accidentally create duplicate companies instead
+ * of joining the existing company they were invited to.
+ */
+
+!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]="853f43ae-d902-54b9-9279-8a4b1d5f7693")}catch(e){}}();
+export function buildCreateCompanyWarning() {
+    return ("  This creates a NEW company that you own — it does NOT join an existing one.\n" +
+        "  If your company already uses HQ, do NOT create it again: ask your admin or owner to send you an invite, then accept it and run `hq sync` to pull the existing company.\n" +
+        "  Creating a same-named company makes a separate one you'd be alone in.\n");
+}
+//# sourceMappingURL=onboard-warning.js.map
+//# debugId=853f43ae-d902-54b9-9279-8a4b1d5f7693

package/dist/commands/onboard.js

@@ -19,13 +19,14 @@
  * browser-OAuth flow opens automatically.
  */
 
-!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]="05a49c9b-23bc-5b96-b5e1-cc2e573b11c3")}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]="235a4623-0834-5428-957c-0c8bbe96d089")}catch(e){}}();
 import chalk from "chalk";
 import { runOnboardCli, readCheckpoint } from "@indigoai-us/hq-onboarding";
 import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 import { createDefaultVaultClient } from "./cloud-provision.js";
 import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
 import { planOnboardJoin } from "./onboard-join.js";
+import { buildCreateCompanyWarning } from "./onboard-warning.js";
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -49,9 +50,7 @@ export function registerOnboardCommand(program) {
             console.log(`  Company:  ${options.name} (${options.slug})`);
             console.log(`  Person:   ${options.personName} <${options.email}>`);
             console.log(`  HQ root:  ${options.hqRoot}\n`);
-            console.log(chalk.gray("  This creates a NEW company you own. Joining a teammate's existing\n" +
-                "  company? Stop — accept your invite, then run `hq sync` to pull it.\n" +
-                "  Creating a same-named company leaves you alone in a separate one.\n"));
+            console.log(chalk.gray(buildCreateCompanyWarning()));
             const accessToken = await ensureCognitoToken();
             const result = await runOnboardCli({
                 mode: "create-company",
@@ -179,6 +178,7 @@ export function registerOnboardCommand(program) {
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .action(async (options) => {
         try {
+            console.log(chalk.gray(buildCreateCompanyWarning()));
             // No auth needed for dry-run — runOnboardCli handles this branch
             // without touching the vault-service.
             const result = await runOnboardCli({
@@ -198,4 +198,4 @@ export function registerOnboardCommand(program) {
     });
 }
 //# sourceMappingURL=onboard.js.map
-//# debugId=05a49c9b-23bc-5b96-b5e1-cc2e573b11c3
+//# debugId=235a4623-0834-5428-957c-0c8bbe96d089

package/dist/commands/pack-install.d.ts

@@ -259,6 +259,18 @@ export declare function verifyArtifact(input: VerifyArtifactInput): void;
  */
 export declare function validateMcpManifest(payloadDir: string, item: string): void;
 export declare function validateManifest(payloadDir: string, hqVersion: string | null): PackManifest;
+/**
+ * Enforce a pack's `requires.packs`: every named dependency MUST already be
+ * installed (and satisfy its optional semver RANGE) before we write anything.
+ *
+ * Installed packs are discovered by FILESYSTEM PRESENCE via `listInstalledPacks`
+ * — deliberately NOT `modules.yaml`, which `installPack` no longer writes under
+ * the v12+ layout (a modules.yaml-based check would silently ignore every modern
+ * pack). Throws on the first unmet dependency so the install aborts with NO
+ * partial state (it is called before installToPackages). No-op when
+ * `requires.packs` is absent/empty, keeping legacy packs unaffected.
+ */
+export declare function assertPackDependencies(hqRoot: string, pkg: PackManifest): void;
 /**
  * Derive the safe, auto-generated "get started" line for a freshly installed
  * pack from its `initialization.entrypoint` ONLY. PHASE 1 deliberately ignores

package/dist/commands/pack-install.js

@@ -34,7 +34,7 @@
  * from each pack's package.yaml; rationale lives in the layout-fix PR.)
  */
 
-!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]="fbfbcf69-d410-51cb-ae59-886c451b3a55")}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]="0ec07d3a-ee86-51fd-adbd-2608c620ae99")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -48,7 +48,7 @@ import semverValid from 'semver/functions/valid.js';
 import semverValidRange from 'semver/ranges/valid.js';
 import semverGt from 'semver/functions/gt.js';
 import { findHqRoot } from '../utils/manifest.js';
-import { readHqVersion, routeContribution } from '../utils/pack-contributions.js';
+import { readHqVersion, routeContribution, listInstalledPacks } from '../utils/pack-contributions.js';
 import { CONTRIBUTION_TABLE, payloadFor } from '../utils/contribution-table.js';
 import { safeExtractTarball } from './safe-extract.js';
 import { vaultApiFetchPublic } from '../utils/vault-api.js';
@@ -907,6 +907,32 @@ export function validateManifest(payloadDir, hqVersion) {
     if (hqVersion && !semverSatisfies(hqVersion, range, { includePrerelease: true })) {
         throw new Error(`Host hqCore ${hqVersion} does not satisfy pack requirement ${range}`);
     }
+    // 6b. requires.packs (M0) — OPTIONAL pack-to-pack dependencies. Absent → legacy
+    // behavior (hqCore is the only prerequisite). Present → a list of
+    // { name, version? } where `name` is a valid hq-pack name and `version` (if
+    // given) is a valid semver RANGE. SHAPE validation only (no filesystem) so a
+    // malformed dependency can't masquerade as valid; whether the named packs are
+    // actually INSTALLED is enforced at install time by assertPackDependencies
+    // (which needs hqRoot — a pure manifest validator doesn't have it).
+    const reqPacks = m.requires?.packs;
+    if (reqPacks !== undefined) {
+        if (!Array.isArray(reqPacks)) {
+            throw new Error('requires.packs must be a list of { name, version? } entries');
+        }
+        for (const dep of reqPacks) {
+            if (!dep || typeof dep !== 'object' || Array.isArray(dep)) {
+                throw new Error('requires.packs entries must be mappings with a name (and optional version)');
+            }
+            const d = dep;
+            if (typeof d.name !== 'string' || !/^hq-pack-[a-z0-9][a-z0-9-]*$/.test(d.name)) {
+                throw new Error(`requires.packs[].name "${d.name}" must match ^hq-pack-[a-z0-9][a-z0-9-]*$`);
+            }
+            if (d.version !== undefined &&
+                (typeof d.version !== 'string' || !semverValidRange(d.version))) {
+                throw new Error(`requires.packs entry for "${d.name}" has an invalid version range "${d.version}"`);
+            }
+        }
+    }
     // 7. contributes has at least one non-empty subfield
     const contributes = (m.contributes ?? {});
     const nonEmpty = Object.values(contributes).some((v) => Array.isArray(v) && v.length > 0);
@@ -1007,6 +1033,46 @@ export function validateManifest(payloadDir, hqVersion) {
     return m;
 }
 // ---------------------------------------------------------------------------
+// Pack-to-pack dependency pre-flight (M0)
+// ---------------------------------------------------------------------------
+/**
+ * Enforce a pack's `requires.packs`: every named dependency MUST already be
+ * installed (and satisfy its optional semver RANGE) before we write anything.
+ *
+ * Installed packs are discovered by FILESYSTEM PRESENCE via `listInstalledPacks`
+ * — deliberately NOT `modules.yaml`, which `installPack` no longer writes under
+ * the v12+ layout (a modules.yaml-based check would silently ignore every modern
+ * pack). Throws on the first unmet dependency so the install aborts with NO
+ * partial state (it is called before installToPackages). No-op when
+ * `requires.packs` is absent/empty, keeping legacy packs unaffected.
+ */
+export function assertPackDependencies(hqRoot, pkg) {
+    const deps = pkg.requires?.packs ?? [];
+    if (deps.length === 0)
+        return;
+    const installed = new Map();
+    for (const p of listInstalledPacks(hqRoot)) {
+        // Key on the manifest name when readable, else the directory name.
+        installed.set(p.manifest?.name ?? p.name, p.manifest?.version);
+    }
+    for (const dep of deps) {
+        if (dep.name === pkg.name) {
+            throw new Error(`Pack ${pkg.name} cannot list itself in requires.packs.`);
+        }
+        if (!installed.has(dep.name)) {
+            throw new Error(`Pack ${pkg.name} requires ${dep.name}, which is not installed. ` +
+                `Install it first, e.g.: hq install marketplace:${dep.name}`);
+        }
+        if (dep.version) {
+            const have = installed.get(dep.name);
+            if (!have || !semverSatisfies(have, dep.version, { includePrerelease: true })) {
+                throw new Error(`Pack ${pkg.name} requires ${dep.name} ${dep.version}, but ` +
+                    `${dep.name}${have ? ` ${have}` : ' (version unknown)'} is installed.`);
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // Post-install get-started line (US-005)
 // ---------------------------------------------------------------------------
 /**
@@ -1482,6 +1548,11 @@ export async function installPack(source, opts = {}) {
                 break;
         }
         const pkg = validateManifest(fetched.payloadDir, hqVersion);
+        // M0 — pack-to-pack dependency pre-flight. Runs BEFORE any prompts or writes
+        // so a missing/unsatisfied `requires.packs` aborts with no partial state, and
+        // before we bother the operator with hook/MCP trust prompts for a pack that
+        // can't install anyway.
+        assertPackDependencies(hqRoot, pkg);
         if (pkg.conditional) {
             const allowed = await confirmConditional(pkg, opts.allowHooks ?? false);
             if (!allowed) {
@@ -1558,4 +1629,4 @@ export async function installPack(source, opts = {}) {
     }
 }
 //# sourceMappingURL=pack-install.js.map
-//# debugId=fbfbcf69-d410-51cb-ae59-886c451b3a55
+//# debugId=0ec07d3a-ee86-51fd-adbd-2608c620ae99

package/dist/commands/packs.js

@@ -18,7 +18,7 @@
  * Spec: knowledge/public/hq-core/package-yaml-spec.md.
  */
 
-!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]="570f7491-8d05-577c-8bae-6f6cf7dfb2ec")}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]="69746edd-f9d8-528e-8902-de799c58bd8a")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
@@ -27,7 +27,7 @@ import chalk from 'chalk';
 import semverSatisfies from 'semver/functions/satisfies.js';
 import { findHqRoot } from '../utils/manifest.js';
 import { classify, resolveLatest, resolveLatestMarketplace, runScanPackages, installPack, } from './pack-install.js';
-import { contributionLinks, linkStatus, listInstalledPacks, readPackManifest, unwirePack, unwirePackMcp, readHqVersion, readRecommendedPackages, packagesDir, } from '../utils/pack-contributions.js';
+import { contributionLinks, linkStatus, listInstalledPacks, findDependentPacks, readPackManifest, unwirePack, unwirePackMcp, readHqVersion, readRecommendedPackages, packagesDir, } from '../utils/pack-contributions.js';
 function resolveRoot(opts) {
     return opts.hqRoot ? path.resolve(opts.hqRoot) : findHqRoot();
 }
@@ -278,6 +278,19 @@ async function runUninstall(name, opts) {
     if (!manifest) {
         warnings.push('package.yaml unreadable -- host symlinks could not be computed precisely; ran a re-scan to reconcile.');
     }
+    // 0. Dependents guard (M0): refuse to remove a pack that another installed pack
+    // lists in its `requires.packs`, unless --force. Filesystem presence is the
+    // source of truth (listInstalledPacks), consistent with the install-time
+    // assertPackDependencies check. Runs BEFORE any un-wiring so a blocked uninstall
+    // leaves the pack fully intact.
+    if (!opts.force) {
+        const dependents = findDependentPacks(listInstalledPacks(hqRoot), name);
+        if (dependents.length > 0) {
+            const who = dependents.map((p) => p.manifest?.name ?? p.name).join(', ');
+            throw new Error(`Cannot uninstall "${name}": required by ${who}. ` +
+                `Uninstall the dependent pack(s) first, or pass --force to override.`);
+        }
+    }
     // 1. Un-wire only our symlinks.
     const { unlinked, skipped } = unwirePack(hqRoot, packDir, contributes);
     // 1b. Un-register the pack's MCP (`wire: 'merge'`) servers — invisible to the
@@ -417,6 +430,7 @@ export function registerPacksCommand(parent) {
         .option('--hq-root <path>', 'HQ root (default: auto-detect)')
         .option('-y, --yes', 'Skip confirmation')
         .option('--no-archive', 'Delete instead of archiving')
+        .option('--force', 'Uninstall even if other installed packs require this one')
         .action(async (name, opts) => {
         try {
             if (!opts.yes) {
@@ -449,4 +463,4 @@ export function registerPacksCommand(parent) {
     });
 }
 //# sourceMappingURL=packs.js.map
-//# debugId=570f7491-8d05-577c-8bae-6f6cf7dfb2ec
+//# debugId=69746edd-f9d8-528e-8902-de799c58bd8a

package/dist/types.d.ts

@@ -75,13 +75,31 @@ export interface PackAuthor {
     handle: string;
     displayName: string;
 }
+/**
+ * A pack-to-pack dependency (M0). OPTIONAL and backwards-compatible — packs
+ * published before this field omit `requires.packs` and install unchanged. When
+ * present, each entry names another content pack that MUST already be installed
+ * before this one (enforced at install time by `assertPackDependencies`, which
+ * tracks installed packs by FILESYSTEM PRESENCE — not `modules.yaml`). `version`
+ * is an optional semver RANGE the installed dependency must satisfy.
+ */
+export interface PackDependency {
+    name: string;
+    version?: string;
+}
 export interface PackManifest {
     name: string;
     version: string;
     publisher: string;
     access: 'public' | 'private';
+    /**
+     * Host + pack prerequisites. `hqCore` is a required semver RANGE the host HQ
+     * must satisfy. `packs` (M0) is an OPTIONAL list of other content packs that
+     * must be installed first — see PackDependency.
+     */
     requires: {
         hqCore: string;
+        packs?: PackDependency[];
     };
     contributes: Partial<Record<PackContributeKey, string[]>>;
     description?: string;

package/dist/utils/pack-contributions.d.ts

@@ -100,6 +100,13 @@ export declare function readPackManifest(packDir: string): {
  * of truth for installed content packs.
  */
 export declare function listInstalledPacks(hqRoot: string): InstalledPack[];
+/**
+ * Installed packs that declare `name` in their `requires.packs` (M0). Pure over
+ * the supplied list — the uninstall dependents guard calls this with
+ * `listInstalledPacks(hqRoot)`. Excludes the pack named `name` itself, so a
+ * self-reference never counts as its own dependent.
+ */
+export declare function findDependentPacks(installed: InstalledPack[], name: string): InstalledPack[];
 export interface UnwireResult {
     unlinked: Array<{
         key: PackContributeKey;

package/dist/utils/pack-contributions.js

@@ -37,7 +37,7 @@
  *     `merge` rows -- they never produce a symlink.
  */
 
-!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]="6cc0fc56-5a1c-5ce8-96d4-652805e508f8")}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]="63e778df-65dd-51a4-8a43-3a7d2aa9a451")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
@@ -213,6 +213,16 @@ export function listInstalledPacks(hqRoot) {
     }
     return out;
 }
+/**
+ * Installed packs that declare `name` in their `requires.packs` (M0). Pure over
+ * the supplied list — the uninstall dependents guard calls this with
+ * `listInstalledPacks(hqRoot)`. Excludes the pack named `name` itself, so a
+ * self-reference never counts as its own dependent.
+ */
+export function findDependentPacks(installed, name) {
+    return installed.filter((p) => p.name !== name &&
+        (p.manifest?.requires?.packs ?? []).some((d) => d.name === name));
+}
 /**
  * Remove only the host symlinks that resolve into THIS pack's directory
  * (status `live` or `broken`). Foreign links and real files are left in place
@@ -318,4 +328,4 @@ export function readRecommendedPackages(hqRoot) {
     }
 }
 //# sourceMappingURL=pack-contributions.js.map
-//# debugId=6cc0fc56-5a1c-5ce8-96d4-652805e508f8
+//# debugId=63e778df-65dd-51a4-8a43-3a7d2aa9a451

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

@@ -27,16 +27,49 @@
  * Opt-out: `HQ_NO_UPDATE_CHECK=1` (same env as `version-check.ts` — one knob
  * to silence both check + gate).
  */
+interface VersionCheckResponse {
+    clientId: string;
+    currentVersion: string;
+    minVersion: string;
+    latestVersion: string;
+    updateRequired: boolean;
+    updateRecommended: boolean;
+    updateCommand?: string;
+    downloadUrl?: string;
+    message?: string;
+}
+export declare function npmPrefixFromPackageDir(pkgDir: string): string | null;
+export declare function resolveRunningPrefix(): string | null;
+export declare function buildPrefixedInstallArgv(prefix: string): string[];
 /**
  * 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): {
+type UpdateResult = {
     ok: boolean;
     detail?: string;
 };
+type UpdateRunner = (cmd: string, args: string[]) => UpdateResult;
+declare function runUpdateCommand(cmd: string, args: string[]): UpdateResult;
+declare function performUpdateCommand(cmd: string, args: string[], runner?: UpdateRunner): UpdateResult;
+declare function performUpdate(command: string, runner?: UpdateRunner): UpdateResult;
+/**
+ * Hard enforcement when the server says we're below `minVersion`. Print a
+ * red banner, attempt the update, then exit so the user reruns against the
+ * fresh binary. Sequence chosen so a user with a broken `npm` global prefix
+ * still gets a clear error rather than an opaque silent failure.
+ *
+ * Exit codes:
+ *   0 — update succeeded; user must rerun their command
+ *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
+ */
+declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: {
+    performUpdateString?: (command: string) => UpdateResult;
+    resolvePrefix?: () => string | null;
+    runner?: UpdateRunner;
+}): never;
 /**
  * Public entry point. Call before commander parses argv. Blocks the CLI on
  * network IO for up to FETCH_TIMEOUT_MS — acceptable because the alternative
@@ -58,7 +91,13 @@ export declare const __test__: {
     CLIENT_ID: string;
     ENDPOINT_PATH: string;
     FETCH_TIMEOUT_MS: number;
+    buildPrefixedInstallArgv: typeof buildPrefixedInstallArgv;
+    enforceUpdateRequired: typeof enforceUpdateRequired;
+    npmPrefixFromPackageDir: typeof npmPrefixFromPackageDir;
     performUpdate: typeof performUpdate;
+    performUpdateCommand: typeof performUpdateCommand;
+    runUpdateCommand: typeof runUpdateCommand;
+    resolveRunningPrefix: typeof resolveRunningPrefix;
 };
 export {};
 //# sourceMappingURL=version-gate.d.ts.map

package/dist/utils/version-gate.js

@@ -28,17 +28,66 @@
  * to silence both check + gate).
  */
 
-!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]="d7d58261-f0e4-56bc-b6eb-4117731744f9")}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]="0f613895-ad4a-5211-bf75-a2e843782c47")}catch(e){}}();
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import chalk from "chalk";
-import { CLI_VERSION } from "../cli-version.js";
+import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
 const CLIENT_ID = "hq-cli";
 const ENDPOINT_PATH = "/v1/client-version/check";
 const FETCH_TIMEOUT_MS = 3_000;
+const LATEST_PACKAGE_SPEC = `${CLI_NAME}@latest`;
 function isOptedOut() {
     return process.env.HQ_NO_UPDATE_CHECK === "1";
 }
+function findRunningPackageRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        try {
+            const pkg = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf-8"));
+            if (pkg.name === CLI_NAME)
+                return dir;
+        }
+        catch {
+            // Keep walking; compiled installs usually start under dist/.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function npmPrefixFromPackageDir(pkgDir) {
+    const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    const segments = normalized.split("/");
+    const nodeModulesIndex = segments.lastIndexOf("node_modules");
+    if (nodeModulesIndex === -1)
+        return null;
+    const prefixEnd = segments[nodeModulesIndex - 1] === "lib"
+        ? nodeModulesIndex - 1
+        : nodeModulesIndex;
+    const prefix = segments.slice(0, prefixEnd).join("/");
+    if (prefix === "" && normalized.startsWith("/"))
+        return "/";
+    return prefix || null;
+}
+export function resolveRunningPrefix() {
+    try {
+        const pkgRoot = findRunningPackageRoot();
+        if (!pkgRoot)
+            return null;
+        return npmPrefixFromPackageDir(pkgRoot);
+    }
+    catch {
+        return null;
+    }
+}
+export function buildPrefixedInstallArgv(prefix) {
+    return ["install", "-g", "--prefix", prefix, LATEST_PACKAGE_SPEC];
+}
 /**
  * Hit POST /v1/client-version/check. Returns the parsed body on 200, or
  * `null` on any failure (caller treats as "no gate"). Tight 3s timeout —
@@ -74,18 +123,7 @@ async function fetchVersionDecision() {
         return null;
     }
 }
-/**
- * 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.
- */
-function performUpdate(command) {
-    const parts = command.split(/\s+/).filter(Boolean);
-    if (parts.length === 0)
-        return { ok: false, detail: "empty command" };
-    const cmd = parts[0];
-    const args = parts.slice(1);
+function runUpdateCommand(cmd, args) {
     try {
         const result = spawnSync(cmd, args, { stdio: "inherit" });
         if (result.status !== 0) {
@@ -100,6 +138,17 @@ function performUpdate(command) {
         return { ok: false, detail: err instanceof Error ? err.message : String(err) };
     }
 }
+function performUpdateCommand(cmd, args, runner = runUpdateCommand) {
+    return runner(cmd, args);
+}
+function performUpdate(command, runner = runUpdateCommand) {
+    const parts = command.split(/\s+/).filter(Boolean);
+    if (parts.length === 0)
+        return { ok: false, detail: "empty command" };
+    const cmd = parts[0];
+    const args = parts.slice(1);
+    return performUpdateCommand(cmd, args, runner);
+}
 /**
  * Soft notify when the server says we're below `latestVersion` but still ≥
  * `minVersion`. Single chalk-yellow line on stderr; never blocks.
@@ -121,24 +170,40 @@ function nudgeUpdateRecommended(decision) {
  *   0 — update succeeded; user must rerun their command
  *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
  */
-function enforceUpdateRequired(decision) {
+function enforceUpdateRequired(decision, deps = {}) {
     const banner = chalk.red.bold(`✗ hq-cli ${decision.currentVersion} is below the minimum required version (${decision.minVersion}).`);
     console.error(banner);
     if (decision.message)
         console.error(chalk.dim(`  ${decision.message}`));
     const command = decision.updateCommand;
-    if (!command) {
+    const prefix = (deps.resolvePrefix ?? resolveRunningPrefix)();
+    if (!command && !prefix) {
         console.error(chalk.red("  No updateCommand provided by hq-pro — see https://hq.indigo.ai/docs/cli-update for manual steps."));
         if (decision.downloadUrl) {
             console.error(chalk.dim(`  Download: ${decision.downloadUrl}`));
         }
         process.exit(75);
     }
-    console.error(chalk.dim(`  Running: ${command}`));
-    const result = performUpdate(command);
+    const runner = deps.runner ?? runUpdateCommand;
+    const result = prefix
+        ? (() => {
+            const args = buildPrefixedInstallArgv(prefix);
+            console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
+            console.error(chalk.dim(`  Running: npm ${args.join(" ")}`));
+            return performUpdateCommand("npm", args, runner);
+        })()
+        : (() => {
+            console.error(chalk.dim(`  Running: ${command}`));
+            return deps.performUpdateString
+                ? deps.performUpdateString(command)
+                : performUpdate(command, runner);
+        })();
     if (!result.ok) {
         console.error(chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`));
-        console.error(chalk.dim(`  Try manually: ${command}`));
+        const manual = prefix
+            ? `npm ${buildPrefixedInstallArgv(prefix).join(" ")}`
+            : command;
+        console.error(chalk.dim(`  Try manually: ${manual}`));
         process.exit(75);
     }
     console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
@@ -179,7 +244,13 @@ export const __test__ = {
     CLIENT_ID,
     ENDPOINT_PATH,
     FETCH_TIMEOUT_MS,
+    buildPrefixedInstallArgv,
+    enforceUpdateRequired,
+    npmPrefixFromPackageDir,
     performUpdate,
+    performUpdateCommand,
+    runUpdateCommand,
+    resolveRunningPrefix,
 };
 //# sourceMappingURL=version-gate.js.map
-//# debugId=d7d58261-f0e4-56bc-b6eb-4117731744f9
+//# debugId=0f613895-ad4a-5211-bf75-a2e843782c47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.50.1",
+  "version": "5.50.2",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/onboard-warning.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import { buildCreateCompanyWarning } from "./onboard-warning.js";
+
+describe("buildCreateCompanyWarning", () => {
+  it("documents the warning shown on the create-company path", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toContain("NEW company");
+    expect(warning).toMatch(/does NOT join an existing one/i);
+  });
+
+  it("advises existing-company users to ask an admin or owner for an invite", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toMatch(/ask your admin or owner.*invite/i);
+  });
+
+  it("tells invitees to run hq sync after accepting", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toContain("accept it and run `hq sync`");
+  });
+
+  it("warns that duplicate creation leaves the user alone in a separate company", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toMatch(/separate one you'd be alone in/i);
+  });
+});

package/src/commands/onboard-warning.ts

@@ -0,0 +1,12 @@
+/**
+ * Builds the static create-time warning surfaced by both `create-company` and
+ * `dry-run`, because users may accidentally create duplicate companies instead
+ * of joining the existing company they were invited to.
+ */
+export function buildCreateCompanyWarning(): string {
+  return (
+    "  This creates a NEW company that you own — it does NOT join an existing one.\n" +
+    "  If your company already uses HQ, do NOT create it again: ask your admin or owner to send you an invite, then accept it and run `hq sync` to pull the existing company.\n" +
+    "  Creating a same-named company makes a separate one you'd be alone in.\n"
+  );
+}

package/src/commands/onboard.ts

@@ -32,6 +32,7 @@ import {
 import { createDefaultVaultClient } from "./cloud-provision.js";
 import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
 import { planOnboardJoin } from "./onboard-join.js";
+import { buildCreateCompanyWarning } from "./onboard-warning.js";
 
 // ---------------------------------------------------------------------------
 // Command registration
@@ -70,13 +71,7 @@ export function registerOnboardCommand(program: Command): void {
         console.log(`  Company:  ${options.name} (${options.slug})`);
         console.log(`  Person:   ${options.personName} <${options.email}>`);
         console.log(`  HQ root:  ${options.hqRoot}\n`);
-        console.log(
-          chalk.gray(
-            "  This creates a NEW company you own. Joining a teammate's existing\n" +
-              "  company? Stop — accept your invite, then run `hq sync` to pull it.\n" +
-              "  Creating a same-named company leaves you alone in a separate one.\n",
-          ),
-        );
+        console.log(chalk.gray(buildCreateCompanyWarning()));
 
         const accessToken = await ensureCognitoToken();
         const result = await runOnboardCli({
@@ -248,6 +243,8 @@ export function registerOnboardCommand(program: Command): void {
     )
     .action(async (options: { hqRoot: string }) => {
       try {
+        console.log(chalk.gray(buildCreateCompanyWarning()));
+
         // No auth needed for dry-run — runOnboardCli handles this branch
         // without touching the vault-service.
         const result = await runOnboardCli({