@indigoai-us/hq-cli 5.50.2 → 5.51.0

package/dist/bin/hq-auth-refresh.d.ts

@@ -10,5 +10,5 @@
  * machine-token mint). Exit 1 if no valid session could be ensured
  * non-interactively.
  */
-export {};
+import "../node-preflight.js";
 //# sourceMappingURL=hq-auth-refresh.d.ts.map

package/dist/bin/hq-auth-refresh.js

@@ -10,8 +10,11 @@
  * machine-token mint). Exit 1 if no valid session could be ensured
  * non-interactively.
  */
+// MUST be first: guard the Node version before any dependency that needs a
+// Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 
-!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]="03d2c531-f620-5d93-a87b-9a87264ad77b")}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]="3c7e1b4e-66dc-5fe8-b828-cd3636df1fbb")}catch(e){}}();
+import "../node-preflight.js";
 import { initSentry, Sentry } from "../sentry.js";
 import { refreshCachedSession } from "../utils/cognito-session.js";
 initSentry();
@@ -38,4 +41,4 @@ initSentry();
     }
 })();
 //# sourceMappingURL=hq-auth-refresh.js.map
-//# debugId=03d2c531-f620-5d93-a87b-9a87264ad77b
+//# debugId=3c7e1b4e-66dc-5fe8-b828-cd3636df1fbb

package/dist/commands/members.d.ts

@@ -12,6 +12,22 @@ export interface PendingInvite {
     invitedBy: string;
     invitedAt: string;
 }
+/**
+ * An ACTIVE member of a company, as returned by
+ * `GET /membership/company/{companyUid}`. The server filters to
+ * `status: "active"` and enriches each row with resolved person metadata
+ * (`personEmail` / `personName` / `personSlug`) when available.
+ */
+export interface ActiveMember {
+    membershipKey: string;
+    personUid: string;
+    companyUid: string;
+    role: string;
+    status: string;
+    personEmail?: string;
+    personName?: string;
+    personSlug?: string;
+}
 export interface InviteOptions {
     target: string;
     role: string;
@@ -114,6 +130,7 @@ export declare class InviteHttpError extends Error {
 }
 export declare function formatInviteHttpError(status: number, fallback: string, code?: string): string;
 export declare function listPendingInvites(token: string, companyUid: string): Promise<PendingInvite[]>;
+export declare function listActiveMembers(token: string, companyUid: string): Promise<ActiveMember[]>;
 /**
  * Resolve a `revoke` CLI argument into the canonical `membershipKey` shape
  * the server requires. Accepts three input forms:

package/dist/commands/members.js

@@ -1,5 +1,5 @@
 
-!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]="40f5379c-742e-5cd5-aba2-931856dc7dd3")}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]="8244d720-094e-5d4e-b813-75086ed0849d")}catch(e){}}();
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
@@ -196,6 +196,20 @@ export async function listPendingInvites(token, companyUid) {
     const data = (await res.json());
     return data?.pending ?? data?.invites ?? [];
 }
+export async function listActiveMembers(token, companyUid) {
+    const res = await vaultApiFetch({
+        token,
+        path: `/membership/company/${encodeURIComponent(companyUid)}`,
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        throw new InviteHttpError(res.status, err.message ?? err.error ?? res.statusText, err.code);
+    }
+    // Server schema: `{ members: [...] }` — active members only, enriched with
+    // resolved person metadata (personEmail / personName / personSlug).
+    const data = (await res.json());
+    return data?.members ?? [];
+}
 /**
  * Resolve a `revoke` CLI argument into the canonical `membershipKey` shape
  * the server requires. Accepts three input forms:
@@ -422,43 +436,66 @@ export function registerMembersCommand(program) {
     });
     members
         .command("list")
-        .description("List pending invites for the company")
-        .action(async () => {
+        .description("List the company's active members (use --pending for pending invites)")
+        .option("--pending", "List pending invites instead of active members")
+        .action(async (opts) => {
         try {
             const token = await ensureCognitoToken();
             const companySlug = members.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
-            const invites = await listPendingInvites(token, companyUid);
-            if (invites.length === 0) {
-                console.log(chalk.gray("No pending invites for this company."));
+            if (opts.pending) {
+                // --pending: preserve the original pending-invites view verbatim.
+                const invites = await listPendingInvites(token, companyUid);
+                if (invites.length === 0) {
+                    console.log(chalk.gray("No pending invites for this company."));
+                    return;
+                }
+                const targetW = Math.max(6, ...invites.map((i) => (i.inviteeEmail ?? i.personUid ?? "").length));
+                const roleW = Math.max(4, ...invites.map((i) => i.role.length));
+                const byW = Math.max(10, ...invites.map((i) => i.invitedBy.length));
+                const keyW = Math.max(14, ...invites.map((i) => i.membershipKey.length));
+                console.log(chalk.bold([
+                    "TARGET".padEnd(targetW),
+                    "ROLE".padEnd(roleW),
+                    "INVITED_BY".padEnd(byW),
+                    "INVITED_AT",
+                    "MEMBERSHIP_KEY".padEnd(keyW),
+                ].join("  ")));
+                for (const inv of invites) {
+                    const target = inv.inviteeEmail ?? inv.personUid ?? "";
+                    console.log([
+                        target.padEnd(targetW),
+                        inv.role.padEnd(roleW),
+                        inv.invitedBy.padEnd(byW),
+                        shortDate(inv.invitedAt),
+                        inv.membershipKey.padEnd(keyW),
+                    ].join("  "));
+                }
+                return;
+            }
+            // Default: list ACTIVE members so their emails drop straight into
+            // `hq secrets share <path> --with <email>`.
+            const activeMembers = await listActiveMembers(token, companyUid);
+            if (activeMembers.length === 0) {
+                console.log(chalk.gray("No active members found for this company."));
                 return;
             }
-            const targetW = Math.max(6, ...invites.map((i) => (i.inviteeEmail ?? i.personUid ?? "").length));
-            const roleW = Math.max(4, ...invites.map((i) => i.role.length));
-            const byW = Math.max(10, ...invites.map((i) => i.invitedBy.length));
-            const keyW = Math.max(14, ...invites.map((i) => i.membershipKey.length));
-            console.log(chalk.bold([
-                "TARGET".padEnd(targetW),
-                "ROLE".padEnd(roleW),
-                "INVITED_BY".padEnd(byW),
-                "INVITED_AT",
-                "MEMBERSHIP_KEY".padEnd(keyW),
-            ].join("  ")));
-            for (const inv of invites) {
-                const target = inv.inviteeEmail ?? inv.personUid ?? "";
-                console.log([
-                    target.padEnd(targetW),
-                    inv.role.padEnd(roleW),
-                    inv.invitedBy.padEnd(byW),
-                    shortDate(inv.invitedAt),
-                    inv.membershipKey.padEnd(keyW),
-                ].join("  "));
+            const emailW = Math.max(5, ...activeMembers.map((m) => (m.personEmail ?? m.personUid).length));
+            const roleW = Math.max(4, ...activeMembers.map((m) => m.role.length));
+            console.log(chalk.bold(["EMAIL".padEnd(emailW), "ROLE".padEnd(roleW), "NAME"].join("  ")));
+            for (const m of activeMembers) {
+                const email = m.personEmail ?? m.personUid;
+                const name = m.personName ?? m.personSlug ?? "";
+                console.log([email.padEnd(emailW), m.role.padEnd(roleW), name].join("  "));
             }
+            console.log(chalk.gray("Share a secret with a member: hq secrets share <path> --with <email>"));
         }
         catch (err) {
             if (err instanceof InviteHttpError) {
                 const msg = err.status === 403
-                    ? "Not authorized — only admins and owners can list invites"
+                    ? opts.pending
+                        ? "Not authorized — only admins and owners can list invites"
+                        : "Not authorized — only company members can list members"
                     : formatInviteHttpError(err.status, err.message);
                 console.error(chalk.red(msg));
                 process.exit(1);
@@ -497,4 +534,4 @@ export function registerMembersCommand(program) {
     });
 }
 //# sourceMappingURL=members.js.map
-//# debugId=40f5379c-742e-5cd5-aba2-931856dc7dd3
+//# debugId=8244d720-094e-5d4e-b813-75086ed0849d

package/dist/commands/people.d.ts

@@ -11,6 +11,16 @@
  * named by `--company`); nothing reads across company boundaries.
  */
 import { Command } from "commander";
+import { resolveNameToEmail, type PersonRecord } from "../utils/people.js";
+export type RefreshPeopleRoster = (hqRoot: string, companySlug: string) => Promise<void>;
+interface PeopleCommandDeps {
+    refreshRoster?: RefreshPeopleRoster;
+}
+interface PeopleLookupOpts {
+    localOnly?: boolean;
+    json?: boolean;
+}
+export declare function refreshPeopleRosterFromCloud(hqRoot: string, companySlug: string): Promise<void>;
 /**
  * Resolve the single company to operate on. Explicit `--company` always wins
  * (after a path-safety check). Otherwise the active company is inferred from
@@ -18,5 +28,20 @@ import { Command } from "commander";
  * do, the caller must disambiguate with `--company`.
  */
 export declare function resolveCompanySlug(hqRoot: string, explicit: string | undefined): string;
-export declare function registerPeopleCommand(program: Command): void;
+export declare function resolvePersonWithRosterFallback(input: {
+    hqRoot: string;
+    slug: string;
+    name: string;
+    opts?: PeopleLookupOpts;
+    refreshRoster?: RefreshPeopleRoster;
+}): Promise<ReturnType<typeof resolveNameToEmail>>;
+export declare function searchPeopleWithRosterFallback(input: {
+    hqRoot: string;
+    slug: string;
+    keyword: string;
+    opts?: PeopleLookupOpts;
+    refreshRoster?: RefreshPeopleRoster;
+}): Promise<PersonRecord[]>;
+export declare function registerPeopleCommand(program: Command, deps?: PeopleCommandDeps): void;
+export {};
 //# sourceMappingURL=people.d.ts.map

package/dist/commands/people.js

@@ -11,14 +11,31 @@
  * named by `--company`); nothing reads across company boundaries.
  */
 
-!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]="076b7f64-6626-5733-8992-ab9361a3e31d")}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]="79abc1f5-4f5a-5c95-b29b-10f04417355f")}catch(e){}}();
 import * as fs from "fs";
 import { Option } from "commander";
 import chalk from "chalk";
+import { VaultClient } from "@indigoai-us/hq-cloud";
 import * as yaml from "js-yaml";
 import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath } from "./cloud-provision.js";
+import { DEFAULT_COGNITO, buildVaultConfig, ensureCognitoToken, } from "../utils/cognito-session.js";
+import { getCompanyUid } from "../utils/vault-api.js";
+import { createCompanyPresignClient, runGet } from "./files-browse.js";
 import { assertSafeCompanySlug, listCompanyPeople, searchPeople, resolveNameToEmail, companyPeopleDir, } from "../utils/people.js";
+export async function refreshPeopleRosterFromCloud(hqRoot, companySlug) {
+    const accessToken = await ensureCognitoToken();
+    const client = new VaultClient(buildVaultConfig(accessToken));
+    await getCompanyUid(accessToken, companySlug);
+    await runGet({
+        path: `companies/${companySlug}/people/`,
+        hqRoot,
+        companySlug,
+        vaultClient: client,
+        companyClient: ({ companyUid }) => createCompanyPresignClient({ token: accessToken, companyUid }),
+        region: DEFAULT_COGNITO.region,
+    });
+}
 /** Companies that still exist (anything not explicitly `status: archived`). */
 function activeCompanySlugs(manifest) {
     const companies = manifest.companies ?? {};
@@ -86,7 +103,39 @@ function fail(message) {
     console.error(chalk.red(message));
     process.exit(1);
 }
-export function registerPeopleCommand(program) {
+function logRefreshFailure(companySlug, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(chalk.dim(`  Could not refresh people roster for '${companySlug}': ${message}`));
+}
+async function tryRefreshRoster(refreshRoster, hqRoot, slug) {
+    try {
+        await refreshRoster(hqRoot, slug);
+        return true;
+    }
+    catch (err) {
+        logRefreshFailure(slug, err);
+        return false;
+    }
+}
+export async function resolvePersonWithRosterFallback(input) {
+    const local = resolveNameToEmail(listCompanyPeople(input.hqRoot, input.slug), input.name);
+    if (local.status !== "not_found" || input.opts?.localOnly)
+        return local;
+    const refreshed = await tryRefreshRoster(input.refreshRoster ?? refreshPeopleRosterFromCloud, input.hqRoot, input.slug);
+    if (!refreshed)
+        return local;
+    return resolveNameToEmail(listCompanyPeople(input.hqRoot, input.slug), input.name);
+}
+export async function searchPeopleWithRosterFallback(input) {
+    const local = searchPeople(listCompanyPeople(input.hqRoot, input.slug), input.keyword);
+    if (local.length > 0 || input.opts?.localOnly)
+        return local;
+    const refreshed = await tryRefreshRoster(input.refreshRoster ?? refreshPeopleRosterFromCloud, input.hqRoot, input.slug);
+    if (!refreshed)
+        return local;
+    return searchPeople(listCompanyPeople(input.hqRoot, input.slug), input.keyword);
+}
+export function registerPeopleCommand(program, deps = {}) {
     const people = program
         .command("people")
         .description("List, search, and resolve a company's people (from companies/<co>/people)")
@@ -122,12 +171,19 @@ export function registerPeopleCommand(program) {
         .command("search <keyword>")
         .description("Keyword search over people names and emails")
         .option("--json", "Output JSON instead of a table")
-        .action((keyword, opts) => {
+        .option("--local-only", "Skip cloud fallback; search only the local people roster")
+        .action(async (keyword, opts) => {
         try {
             const scope = people.opts();
             const hqRoot = resolveHqRoot(scope);
             const slug = resolveCompanySlug(hqRoot, scope.company);
-            const matches = searchPeople(listCompanyPeople(hqRoot, slug), keyword);
+            const matches = await searchPeopleWithRosterFallback({
+                hqRoot,
+                slug,
+                keyword,
+                opts,
+                refreshRoster: deps.refreshRoster,
+            });
             if (opts.json) {
                 console.log(JSON.stringify(matches, null, 2));
                 return;
@@ -146,12 +202,19 @@ export function registerPeopleCommand(program) {
         .command("resolve <name>")
         .description("Resolve a person name to their email address")
         .option("--json", "Output JSON instead of plain text")
-        .action((name, opts) => {
+        .option("--local-only", "Skip cloud fallback; resolve only from the local people roster")
+        .action(async (name, opts) => {
         try {
             const scope = people.opts();
             const hqRoot = resolveHqRoot(scope);
             const slug = resolveCompanySlug(hqRoot, scope.company);
-            const result = resolveNameToEmail(listCompanyPeople(hqRoot, slug), name);
+            const result = await resolvePersonWithRosterFallback({
+                hqRoot,
+                slug,
+                name,
+                opts,
+                refreshRoster: deps.refreshRoster,
+            });
             if (opts.json) {
                 console.log(JSON.stringify(result, null, 2));
                 if (result.status === "found")
@@ -184,4 +247,4 @@ export function registerPeopleCommand(program) {
     });
 }
 //# sourceMappingURL=people.js.map
-//# debugId=076b7f64-6626-5733-8992-ab9361a3e31d
+//# debugId=79abc1f5-4f5a-5c95-b29b-10f04417355f

package/dist/commands/secrets-scope.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure helpers describing WHICH secrets scope a command acted on, so `set` and
+ * `list` can echo it. Users were setting a secret in one scope (personal vs a
+ * company, or company A vs B) and listing another, then seeing "no secrets" with
+ * no indication the scopes differed (feedback_70e059da).
+ */
+export interface SecretsScopeRef {
+    /** True when --personal was used (caller's personal vault). */
+    personal: boolean;
+    /** The slug the user passed via --company, if any. */
+    companySlug?: string;
+    /** Resolved entity uid: prs_* for personal, cmp_* for a company. */
+    companyUid: string;
+}
+/** Human label for a secrets scope: "your personal vault" or "company <slug-or-uid>". */
+export declare function describeSecretsScope(ref: SecretsScopeRef): string;
+export declare function formatSecretSaved(name: string, scope: string): string;
+export declare function formatSecretsListHeader(scope: string): string;
+export declare function formatSecretsListEmpty(scope: string): string;
+//# sourceMappingURL=secrets-scope.d.ts.map

package/dist/commands/secrets-scope.js

@@ -0,0 +1,19 @@
+/** Human label for a secrets scope: "your personal vault" or "company <slug-or-uid>". */
+
+!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]="718913a3-f80f-5bff-928e-a7aa9f51dd0d")}catch(e){}}();
+export function describeSecretsScope(ref) {
+    if (ref.personal)
+        return "your personal vault";
+    return `company ${ref.companySlug ?? ref.companyUid}`;
+}
+export function formatSecretSaved(name, scope) {
+    return `Secret '${name}' saved to ${scope}.`;
+}
+export function formatSecretsListHeader(scope) {
+    return `Secrets for ${scope}:`;
+}
+export function formatSecretsListEmpty(scope) {
+    return `No secrets found for ${scope}.`;
+}
+//# sourceMappingURL=secrets-scope.js.map
+//# debugId=718913a3-f80f-5bff-928e-a7aa9f51dd0d

package/dist/commands/secrets.js

@@ -1,5 +1,5 @@
 
-!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]="3049e431-c5db-5430-90fe-82866c35e95b")}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]="96461f1a-6d5b-5dc0-b00a-0a9fa30a0dad")}catch(e){}}();
 import chalk from "chalk";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
@@ -8,6 +8,7 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { DEFAULT_SECRETS_CACHE_TTL_MS, readCache, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
 import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN } from "./_patterns.js";
+import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
 import { vaultApiFetch, getCompanyUid, getEntityUid, } from "../utils/vault-api.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
 function scopeOpts(opts) {
@@ -344,7 +345,13 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const token = await ensureCognitoToken();
-            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
+            const scope = scopeOpts(secrets.opts());
+            const companyUid = await getEntityUid(token, scope);
+            const scopeLabel = describeSecretsScope({
+                personal: scope.personal,
+                companySlug: scope.companySlug,
+                companyUid,
+            });
             const res = await vaultApiFetch({
                 token,
                 path: `/secrets/${encodeURIComponent(companyUid)}`,
@@ -357,7 +364,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             removeCacheEntry(companyUid, name);
-            console.log(chalk.green(`Secret '${name}' saved.`));
+            console.log(chalk.green(formatSecretSaved(name, scopeLabel)));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -487,7 +494,13 @@ export function registerSecretsCommand(program) {
                 normalizedPrefix = normalized;
             }
             const token = await ensureCognitoToken();
-            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
+            const scope = scopeOpts(secrets.opts());
+            const companyUid = await getEntityUid(token, scope);
+            const scopeLabel = describeSecretsScope({
+                personal: scope.personal,
+                companySlug: scope.companySlug,
+                companyUid,
+            });
             const query = {};
             if (normalizedPrefix) {
                 query.prefix = normalizedPrefix;
@@ -504,7 +517,7 @@ export function registerSecretsCommand(program) {
             }
             const data = (await res.json());
             if (data.secrets.length === 0) {
-                console.log(chalk.dim("No secrets found."));
+                console.log(chalk.dim(formatSecretsListEmpty(scopeLabel)));
                 return;
             }
             const nameWidth = Math.max(4, ...data.secrets.map((s) => s.name.length));
@@ -514,6 +527,7 @@ export function registerSecretsCommand(program) {
             if (hasPermission) {
                 const accessWidth = Math.max(6, ...data.secrets.map((s) => (s.permission ?? "-").length));
                 const header = `${"NAME".padEnd(nameWidth)}  ${"ACCESS".padEnd(accessWidth)}  ${"TIER".padEnd(tierWidth)}  ${"SCRIPT LOCK".padEnd(scriptLockWidth)}  LAST MODIFIED`;
+                console.log(chalk.dim(formatSecretsListHeader(scopeLabel)));
                 console.log(chalk.bold(header));
                 for (const s of data.secrets) {
                     const access = s.permission ?? "-";
@@ -525,6 +539,7 @@ export function registerSecretsCommand(program) {
             }
             else {
                 const header = `${"NAME".padEnd(nameWidth)}  ${"TIER".padEnd(tierWidth)}  ${"SCRIPT LOCK".padEnd(scriptLockWidth)}  LAST MODIFIED`;
+                console.log(chalk.dim(formatSecretsListHeader(scopeLabel)));
                 console.log(chalk.bold(header));
                 for (const s of data.secrets) {
                     const tier = normalizeSecretTier(s.tier);
@@ -1148,4 +1163,4 @@ export function registerSecretsCommand(program) {
     });
 }
 //# sourceMappingURL=secrets.js.map
-//# debugId=3049e431-c5db-5430-90fe-82866c35e95b
+//# debugId=96461f1a-6d5b-5dc0-b00a-0a9fa30a0dad

package/dist/index.d.ts

@@ -2,5 +2,5 @@
 /**
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
-export {};
+import "./node-preflight.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,8 +2,11 @@
 /**
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
+// MUST be first: guard the Node version before any dependency that needs a
+// Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 
-!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]="34e9e978-4c0a-5113-82af-9a33e30686c6")}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]="82c44c14-a953-5644-9bf2-dd2c6d487d63")}catch(e){}}();
+import "./node-preflight.js";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -47,12 +50,18 @@ import { registerRescueCommand } from "./commands/rescue.js";
 import { registerMcpCommand } from "./commands/mcp-status.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { isEpipe } from "./utils/epipe.js";
+import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.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.
+// Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
+// the pipe early. This covers the ASYNC path — an 'error' event emitted on the
+// stream. The SYNCHRONOUS path (a `write EPIPE` thrown straight out of
+// console.log inside a command) is handled in the top-level catch below; both
+// share `isEpipe` (HQ-6B).
 const onPipeError = (err) => {
-    if (err.code === "EPIPE") {
+    if (isEpipe(err)) {
         process.exit(0);
     }
     throw err;
@@ -182,19 +191,40 @@ registerMcpCommand(program);
         await program.parseAsync();
     }
     catch (err) {
-        // A full disk / exhausted quota / read-only filesystem is the user's
-        // machine, not an HQ code defect. Surface a clear, actionable message and
-        // skip Sentry capture so one full disk doesn't flood the tracker with
-        // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
-        // to Sentry and still exit 1.
-        const envMsg = environmentalFsErrorMessage(err);
-        if (envMsg) {
-            process.stderr.write(`hq: ${envMsg}\n`);
+        // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
+        // (`hq … | head`, `source <(hq …)`, a parent that exited). That is normal
+        // Unix behavior with no user-facing degradation — exit cleanly (0) and
+        // skip Sentry capture instead of shipping a fatal (HQ-6B). A synchronous
+        // `write EPIPE` thrown out of console.log lands here rather than on the
+        // stream 'error' listener above.
+        if (isEpipe(err)) {
+            process.exitCode = 0;
+        }
+        else if (isInterceptedProcessExit(err)) {
+            // A security/audit FUZZ harness replaced `process.exit` with a throw so it
+            // can keep exercising the binary. Commander calling `process.exit` for
+            // normal CLI control flow (e.g. an unknown command → exit 1) then surfaces
+            // here as that synthetic marker. It is a test-harness artifact, NOT an
+            // hq-cli defect — a real user's `process.exit` just exits, so nothing is
+            // thrown or captured. Skip Sentry capture (no signal, no user-facing
+            // degradation) and preserve the intended non-zero exit (HQ-CLI-3).
+            process.exitCode = 1;
         }
         else {
-            Sentry.captureException(err);
+            // A full disk / exhausted quota / read-only filesystem is the user's
+            // machine, not an HQ code defect. Surface a clear, actionable message and
+            // skip Sentry capture so one full disk doesn't flood the tracker with
+            // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
+            // to Sentry and still exit 1.
+            const envMsg = environmentalFsErrorMessage(err);
+            if (envMsg) {
+                process.stderr.write(`hq: ${envMsg}\n`);
+            }
+            else {
+                Sentry.captureException(err);
+            }
+            process.exitCode = 1;
         }
-        process.exitCode = 1;
     }
     finally {
         // Release health: finalize the per-run session before the flush.
@@ -203,4 +233,4 @@ registerMcpCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=34e9e978-4c0a-5113-82af-9a33e30686c6
+//# debugId=82c44c14-a953-5644-9bf2-dd2c6d487d63

package/dist/node-preflight.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Runtime Node.js version guard for the hq CLI.
+ *
+ * HQ tooling requires Node.js 20 or newer. On older runtimes (notably Node 18)
+ * the CLI dies with cryptic failures long before reaching any of its own code:
+ * a native-module ABI mismatch from a prebuilt dependency, and a missing
+ * `util.styleText` (added in Node 20). Those errors give the user no hint that
+ * the real problem is just an old Node.
+ *
+ * This module exists to fail fast with an actionable message instead. It is
+ * imported FIRST by every CLI entry point (`index.ts`, `bin/hq-auth-refresh.ts`)
+ * so the check runs before commander, Sentry, or any dependency that needs a
+ * Node 20+ API or a newer native ABI is evaluated. ES modules evaluate their
+ * imports in source order, so as long as this is the first import in the entry
+ * module, the guard short-circuits an unsupported runtime cleanly.
+ *
+ * Keep this file dependency-free — it must not import anything that could itself
+ * fail to load on the very runtime it is trying to detect.
+ */
+export declare const MIN_NODE_MAJOR = 20;
+export interface NodeVersionCheck {
+    ok: boolean;
+    major: number;
+    message?: string;
+}
+/**
+ * Pure check: is the given Node version string (e.g. "18.19.0") supported?
+ * Defaults to the running runtime's version. An unparseable version is treated
+ * as supported so we never block a user on a version string we can't read.
+ */
+export declare function checkNodeVersion(versionString?: string): NodeVersionCheck;
+/**
+ * Side-effecting guard run on import: prints the upgrade message to stderr and
+ * exits 1 on an unsupported runtime. A no-op on Node 20+. Set
+ * `HQ_SKIP_NODE_PREFLIGHT=1` to bypass (used by the test runner, which already
+ * runs on a supported Node).
+ */
+export declare function enforceNodeVersion(): void;
+//# sourceMappingURL=node-preflight.d.ts.map