@indigoai-us/hq-cli 5.100.0 → 5.101.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [5.101.1] — 2026-08-14
+
+### Fixed
+
+- `hq core rebuild-index threads` no longer crashes with an `ENOENT` stat error
+  when a `workspace/threads/T-*.json` entry that the directory scan listed can no
+  longer be resolved — removed mid-scan by a concurrent writer (HQ Sync, another
+  session, or `archive-old-threads`) or left as a dangling symlink. The renderer
+  now stats each file exactly once before sorting (a Schwartzian transform rather
+  than statting inside the sort comparator), skips entries that vanished (logging
+  a single summary line by basename), and still fails loudly on a genuine stat
+  error such as `EACCES`. Both `INDEX.md` and `recent.md` are regenerated as
+  before. Sentry 7669694322 (HQ-CLI-P).
+
+## [5.101.0] — 2026-08-13
+
+### Added
+
+- `hq agents provision` now offers the authoritative Basic, Power, and Dev box
+  sizes during interactive creation and accepts `--size basic|power|dev` for
+  automation. The CLI shows HQ Pro's company-specific monthly quote and
+  capacity before confirmation, carries the quote version into creation so a
+  stale price is refused, and preserves the server default when `--size` is
+  omitted.
+
 ## [5.100.0] — 2026-08-13
 
 ### Added

package/dist/commands/agents.d.ts

@@ -31,6 +31,8 @@ export declare const VALID_TIERS: Set<string>;
 export declare const VALID_PROVIDERS: Set<string>;
 /** Auth modes hq-pro accepts on `POST /v1/agents` (`CodexAuthMode`). */
 export declare const VALID_AUTH_MODES: Set<string>;
+/** Customer-facing agent size keys served by hq-pro's authoritative catalog. */
+export declare const VALID_AGENT_SIZE_KEYS: Set<string>;
 /**
  * Resolve a closed-set option value, or exit(1) with a message naming the
  * offending input and the legal set.
@@ -132,7 +134,47 @@ export interface ProvisionAgentInput {
     idempotencyKey: string;
     title?: string;
     description?: string;
+    /** Omitted to preserve hq-pro's existing default. */
+    desiredInstanceType?: string;
+    /** Server quote assertion; hq-pro re-prices and refuses a stale amount. */
+    quotedNetMonthlyCents?: number;
+    quoteCatalogVersion?: string;
 }
+export interface AgentCreateSizeOption {
+    key: "basic" | "power" | "dev";
+    productName: string;
+    instanceType: string;
+    listCents: number;
+    default: boolean;
+    selectable: boolean;
+    netMonthlyCents: number | null;
+    deltaCents: number | null;
+    unavailableReason: string | null;
+    notBilled: boolean;
+    lanes: number;
+    workers: number;
+}
+export interface AgentCreateOptionsView {
+    defaultInstanceType: string;
+    catalogVersion: string;
+    options: AgentCreateSizeOption[];
+}
+export type QuotedAgentCreateSizeOption = AgentCreateSizeOption & {
+    netMonthlyCents: number;
+    deltaCents: number;
+};
+/** Read hq-pro's company-specific creation prices and capacities. */
+export declare function getAgentCreateOptions(token: string, companyUid: string, idempotencyKey?: string): Promise<AgentCreateOptionsView>;
+/** Resolve a requested size from the server response, never from local prices. */
+export declare function requireQuotedCreateSize(view: AgentCreateOptionsView, sizeKey: string): QuotedAgentCreateSizeOption;
+/** Resolve hq-pro's default quote while leaving the POST default implicit. */
+export declare function requireDefaultAgentCreateSize(view: AgentCreateOptionsView): QuotedAgentCreateSizeOption;
+/** Human-facing quote summary sourced entirely from hq-pro. */
+export declare function formatAgentCreateSize(option: AgentCreateSizeOption): string;
+/** Ask a TTY user to choose one of hq-pro's currently selectable quotes. */
+export declare function promptForAgentCreateSize(view: AgentCreateOptionsView): Promise<QuotedAgentCreateSizeOption>;
+/** Confirm creation using the server quote, preserving $0 as a real answer. */
+export declare function confirmAgentCreateQuoteOrExit(option: QuotedAgentCreateSizeOption, yes?: boolean): void;
 export declare function provisionAgent(token: string, input: ProvisionAgentInput): Promise<{
     uid?: string;
     slug?: string;

package/dist/commands/agents.js

@@ -23,10 +23,11 @@
  */
 import chalk from "chalk";
 import { randomUUID } from "node:crypto";
+import * as readline from "node:readline";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
-import { AGENT_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
+import { confirmChargeOrExit, formatUsd, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
     "minimal",
@@ -41,6 +42,8 @@ export const VALID_TIERS = new Set(["default", "priority"]);
 export const VALID_PROVIDERS = new Set(["codex", "grok", "claude"]);
 /** Auth modes hq-pro accepts on `POST /v1/agents` (`CodexAuthMode`). */
 export const VALID_AUTH_MODES = new Set(["subscription", "apiKey"]);
+/** Customer-facing agent size keys served by hq-pro's authoritative catalog. */
+export const VALID_AGENT_SIZE_KEYS = new Set(["basic", "power", "dev"]);
 /**
  * Resolve a closed-set option value, or exit(1) with a message naming the
  * offending input and the legal set.
@@ -137,6 +140,115 @@ export function slugifyAgentName(name) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
 }
+/** Read hq-pro's company-specific creation prices and capacities. */
+export async function getAgentCreateOptions(token, companyUid, idempotencyKey) {
+    const raw = await agentsRequest({
+        token,
+        path: "/v1/agents/provision-options",
+        query: {
+            companyUid,
+            ...(idempotencyKey ? { idempotencyKey } : {}),
+        },
+    });
+    if (!raw || typeof raw !== "object") {
+        throw new Error("HQ Pro returned an invalid agent size catalog.");
+    }
+    const view = raw;
+    if (typeof view.catalogVersion !== "string" || !view.catalogVersion.trim()) {
+        throw new Error("HQ Pro did not return the catalog version required to protect this price quote.");
+    }
+    if (typeof view.defaultInstanceType !== "string" ||
+        !Array.isArray(view.options)) {
+        throw new Error("HQ Pro returned an invalid agent size catalog.");
+    }
+    return view;
+}
+/** Resolve a requested size from the server response, never from local prices. */
+export function requireQuotedCreateSize(view, sizeKey) {
+    const option = view.options.find((candidate) => candidate.key === sizeKey);
+    if (!option) {
+        throw new Error(`HQ Pro did not return a quote for agent size ${sizeKey}.`);
+    }
+    if (!option.selectable ||
+        typeof option.productName !== "string" ||
+        !option.productName.trim() ||
+        typeof option.instanceType !== "string" ||
+        !option.instanceType.trim() ||
+        typeof option.notBilled !== "boolean" ||
+        option.netMonthlyCents === null ||
+        !Number.isSafeInteger(option.netMonthlyCents) ||
+        option.netMonthlyCents < 0 ||
+        option.deltaCents !== option.netMonthlyCents ||
+        (option.notBilled && option.netMonthlyCents !== 0) ||
+        !Number.isSafeInteger(option.lanes) ||
+        option.lanes < 0 ||
+        !Number.isSafeInteger(option.workers) ||
+        option.workers < 0) {
+        throw new Error(`Agent size ${option.productName} cannot be priced right now` +
+            (option.unavailableReason ? ` (${option.unavailableReason})` : "."));
+    }
+    return option;
+}
+/** Resolve hq-pro's default quote while leaving the POST default implicit. */
+export function requireDefaultAgentCreateSize(view) {
+    const option = view.options.find((candidate) => candidate.default);
+    if (!option || option.instanceType !== view.defaultInstanceType) {
+        throw new Error("HQ Pro did not return a valid default agent size quote.");
+    }
+    return requireQuotedCreateSize(view, option.key);
+}
+/** Human-facing quote summary sourced entirely from hq-pro. */
+export function formatAgentCreateSize(option) {
+    const cost = option.netMonthlyCents === null
+        ? "price unavailable"
+        : `${formatUsd(option.netMonthlyCents)}/month`;
+    return (`${option.productName}: ${cost}; ` +
+        `${option.lanes} lanes; ${option.workers} workers`);
+}
+/** Ask a TTY user to choose one of hq-pro's currently selectable quotes. */
+export async function promptForAgentCreateSize(view) {
+    for (const option of view.options) {
+        console.log(chalk.dim(formatAgentCreateSize(option) +
+            (option.selectable && option.netMonthlyCents !== null
+                ? ""
+                : ` — unavailable${option.unavailableReason ? ` (${option.unavailableReason})` : ""}`)));
+    }
+    const selectable = view.options.filter((option) => option.selectable && option.netMonthlyCents !== null);
+    if (selectable.length === 0) {
+        throw new Error("HQ Pro could not price any agent size right now.");
+    }
+    const legal = selectable.map((option) => option.key).join(" | ");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolve) => rl.question(`Choose agent size (${legal}): `, resolve));
+        const key = canonicalizeOptionValue(answer, new Set(selectable.map((option) => option.key)));
+        if (!key) {
+            throw new Error(`Invalid agent size '${answer}': choose ${legal}.`);
+        }
+        return requireQuotedCreateSize(view, key);
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Confirm creation using the server quote, preserving $0 as a real answer. */
+export function confirmAgentCreateQuoteOrExit(option, yes) {
+    if (option.notBilled || option.netMonthlyCents === 0) {
+        const message = `${option.productName} is ${formatUsd(0)}/month for this company — ` +
+            "there is no per-agent charge.";
+        if (!yes) {
+            console.error(chalk.yellow(`${message}\nRe-run with --yes to confirm agent provisioning.`));
+            process.exit(1);
+        }
+        console.log(chalk.dim(`${message} Provisioning…`));
+        return;
+    }
+    confirmChargeOrExit({
+        resource: "agent",
+        unitCents: option.netMonthlyCents,
+        yes,
+    });
+}
 export async function provisionAgent(token, input) {
     return agentsRequest({
         token,
@@ -387,7 +499,7 @@ export function registerAgentsCommand(program) {
     agents
         .command("provision <name>")
         .alias("new")
-        .description("Provision a new cloud agent ($100/month — requires --yes)")
+        .description("Provision a new cloud agent (company-specific monthly price shown before creation)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--slug <slug>", "Agent slug (defaults to a slug of <name>)")
         .option("--provider <provider>", "Runtime: codex | grok | claude (default codex). claude is subscription-only")
@@ -395,7 +507,8 @@ export function registerAgentsCommand(program) {
         .option("--api-key-env <VAR>", "Env var holding the API key for --auth-mode apiKey (never pass the key as a flag)")
         .option("--title <title>", "Org-chart job title")
         .option("--description <text>", "Short description / bio")
-        .option("--yes", "Confirm the $100/month charge (required to provision)")
+        .option("--size <size>", "Agent box size: basic | power | dev (omitted keeps the current default)")
+        .option("--yes", "Confirm the quoted monthly cost and provision the agent")
         .action(async function (name, opts) {
         try {
             // Both of these previously fell back to their default on an
@@ -430,12 +543,21 @@ export function registerAgentsCommand(program) {
             }
             const token = (await resolveVaultCredential()).token;
             const companyUid = await getCompanyUid(token, companyOf(this));
-            // Paid gate: print the monthly cost and require --yes before any call.
-            confirmChargeOrExit({
-                resource: "agent",
-                unitCents: AGENT_PRICE_CENTS,
-                yes: opts.yes,
-            });
+            const idempotencyKey = `hq-cli-${randomUUID()}`;
+            const sizeKey = parseEnumOption(opts.size, VALID_AGENT_SIZE_KEYS, "--size");
+            const shouldChooseInteractively = !sizeKey && process.stdin.isTTY === true;
+            const createOptions = await getAgentCreateOptions(token, companyUid, idempotencyKey);
+            const quotedSize = sizeKey
+                ? requireQuotedCreateSize(createOptions, sizeKey)
+                : shouldChooseInteractively
+                    ? await promptForAgentCreateSize(createOptions)
+                    : requireDefaultAgentCreateSize(createOptions);
+            if (!shouldChooseInteractively) {
+                console.log(chalk.dim(formatAgentCreateSize(quotedSize)));
+            }
+            // Every path confirms hq-pro's company-specific quote. Omission still
+            // leaves the POST size implicit, preserving the server-side default.
+            confirmAgentCreateQuoteOrExit(quotedSize, opts.yes);
             const slug = opts.slug ?? slugifyAgentName(name);
             try {
                 const result = await provisionAgent(token, {
@@ -445,9 +567,19 @@ export function registerAgentsCommand(program) {
                     codexAuthMode: authMode,
                     ...(provider ? { provider } : {}),
                     ...(codexApiKey ? { codexApiKey } : {}),
-                    idempotencyKey: `hq-cli-${randomUUID()}`,
+                    idempotencyKey,
                     ...(opts.title ? { title: opts.title } : {}),
                     ...(opts.description ? { description: opts.description } : {}),
+                    // Leave hq-pro's current default implicit so a Team setup agent
+                    // still goes through its atomic entitlement claim. Every current
+                    // CLI path nevertheless echoes the displayed amount and catalog
+                    // snapshot, so omitted --size cannot silently accept a price that
+                    // changed between confirmation and creation.
+                    ...(quotedSize.default
+                        ? {}
+                        : { desiredInstanceType: quotedSize.instanceType }),
+                    quotedNetMonthlyCents: quotedSize.netMonthlyCents,
+                    quoteCatalogVersion: createOptions.catalogVersion,
                 });
                 const uid = typeof result.uid === "string" ? result.uid : slug;
                 console.log(chalk.green(`Provisioning started for agent "${name}".`));

package/dist/commands/db-provision.js

@@ -4,6 +4,7 @@
 import chalk from "chalk";
 import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
 import { DEFAULT_VAULT_API_URL, ensureCognitoToken, } from "../utils/cognito-session.js";
+import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { getCompanyUid } from "../utils/vault-api.js";
 const defaultDeps = () => ({
     async resolveCompany(slug) {
@@ -59,6 +60,9 @@ export function registerDbProvisionCommand(db, depsFactory = defaultDeps) {
             console.log(`idempotent: ${result.idempotent ? "yes" : "no"}`);
         }
         catch (error) {
+            // Let main.ts render the shared, non-stacktrace plan-gate message.
+            if (isPlanGateError(error))
+                throw error;
             const msg = error instanceof Error ? error.message : "Unknown error";
             const status = error.status;
             if (status === 402 || /PLAN_REQUIRED|Team plan|\$500/i.test(msg)) {

package/dist/lib/db/control-plane.js

@@ -1,7 +1,4 @@
-/**
- * Control-plane client for remote vault DB (US-009).
- * Injectable fetch for tests — never logs response bodies that might hold secrets.
- */
+import { planGateErrorFromPayload } from "../../utils/plan-gate-error.js";
 function assertNoPostgresUrl(label, text) {
     if (/postgres:\/\//i.test(text) || /postgresql:\/\//i.test(text)) {
         throw new Error(`${label}: control plane returned a connection string (refusing to surface)`);
@@ -30,21 +27,22 @@ export class ControlPlaneDbClient {
         assertNoPostgresUrl("provision", text);
         if (!res.ok) {
             let msg = `provision failed (${res.status})`;
-            let code;
+            let payload;
             try {
-                const j = JSON.parse(text);
-                if (j.error)
-                    msg = j.error;
-                if (j.code)
-                    code = j.code;
+                payload = JSON.parse(text);
+                if (typeof payload.error === "string")
+                    msg = payload.error;
             }
             catch {
                 /* keep */
             }
+            const planGate = planGateErrorFromPayload(res.status, payload);
+            if (planGate)
+                throw planGate;
             const err = new Error(msg);
             err.status = res.status;
-            if (code)
-                err.code = code;
+            if (typeof payload?.code === "string")
+                err.code = payload.code;
             throw err;
         }
         return JSON.parse(text);

package/dist/lib/index-render/shared.d.ts

@@ -31,5 +31,24 @@ export declare function projectStatus(root: string, project: string, prdPath: st
 export declare function basename(file: string): string;
 export declare function isHidden(name: string): boolean;
 export declare function mtime(file: string): number;
+/**
+ * Sort key for newest-first ordering: the file's modification time in
+ * nanoseconds. Stat the file exactly once, before sorting — never from inside a
+ * comparator, where a throw aborts `Array.sort` and an mtime that changes
+ * mid-sort makes the comparator inconsistent.
+ *
+ * Returns `undefined` when the entry a directory scan just listed can no longer
+ * be resolved: it was removed between the `readdirSync` snapshot and this stat
+ * (a time-of-check-to-time-of-use race in a hot, multi-writer directory), or it
+ * is a symlink whose target is missing (`statSync` follows symlinks). Callers
+ * drop such entries — mirroring how `immediateEntries` and `readJson` already
+ * tolerate a vanished file — so the render never crashes on a benign race.
+ *
+ * Any other stat failure (EACCES, EIO, …) is a genuine fault and is rethrown
+ * with the offending file's BASENAME attached, never its absolute path, which
+ * must not reach error reporting such as Sentry. The original errno `code` is
+ * preserved so upstream error classification is unaffected.
+ */
+export declare function sortKeyMtimeNs(file: string): bigint | undefined;
 export declare function tempDirectory(prefix: string): string;
 //# sourceMappingURL=shared.d.ts.map

package/dist/lib/index-render/shared.js

@@ -120,6 +120,38 @@ export function mtime(file) { try {
 catch {
     return 0;
 } }
+/**
+ * Sort key for newest-first ordering: the file's modification time in
+ * nanoseconds. Stat the file exactly once, before sorting — never from inside a
+ * comparator, where a throw aborts `Array.sort` and an mtime that changes
+ * mid-sort makes the comparator inconsistent.
+ *
+ * Returns `undefined` when the entry a directory scan just listed can no longer
+ * be resolved: it was removed between the `readdirSync` snapshot and this stat
+ * (a time-of-check-to-time-of-use race in a hot, multi-writer directory), or it
+ * is a symlink whose target is missing (`statSync` follows symlinks). Callers
+ * drop such entries — mirroring how `immediateEntries` and `readJson` already
+ * tolerate a vanished file — so the render never crashes on a benign race.
+ *
+ * Any other stat failure (EACCES, EIO, …) is a genuine fault and is rethrown
+ * with the offending file's BASENAME attached, never its absolute path, which
+ * must not reach error reporting such as Sentry. The original errno `code` is
+ * preserved so upstream error classification is unaffected.
+ */
+export function sortKeyMtimeNs(file) {
+    try {
+        return fs.statSync(file, { bigint: true }).mtimeNs;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return undefined;
+        const wrapped = new Error(`failed to stat ${basename(file)} (${code ?? "unknown error"})`);
+        if (code !== undefined)
+            wrapped.code = code;
+        throw wrapped;
+    }
+}
 // Kept exported for primitive tests and consumers that need a temp base without
 // relying on an application-specific fixture location.
 export function tempDirectory(prefix) { return fs.mkdtempSync(path.join(os.tmpdir(), prefix)); }

package/dist/lib/index-render/threads.js

@@ -1,19 +1,40 @@
 import * as fs from "fs";
-import { at, log, readJson, sanitize, timestamp, write } from "./shared.js";
+import { at, basename, log, readJson, sanitize, sortKeyMtimeNs, timestamp, write } from "./shared.js";
 export function renderThreads(context, args = []) {
     const mode = args[0] ?? "--index";
     const directory = at(context.root, "workspace/threads");
     fs.mkdirSync(directory, { recursive: true });
     // Match `ls -t`: newest filesystem modification time first. `updated_at` is
     // rendered metadata only, and must not influence the order.
+    //
+    // Stat every listed file exactly once, BEFORE sorting (a Schwartzian
+    // transform), never from inside the comparator. workspace/threads is a hot,
+    // multi-writer directory (HQ Sync reconciliation, concurrent agent sessions,
+    // and `archive-old-threads` renaming T-*.json out of it), so an entry
+    // readdirSync just snapshotted can vanish before it is stat'ed. Statting
+    // inside the comparator turned that time-of-check-to-time-of-use window — and
+    // any dangling symlink — into an ENOENT that aborted the whole command before
+    // either file was written. Precompute the key, drop entries that no longer
+    // resolve (as `readJson` already drops unreadable files), then compare only
+    // precomputed keys so the comparator can neither throw nor be inconsistent.
+    const skipped = [];
     const files = fs.readdirSync(directory)
         .filter((name) => /^T-.*\.json$/.test(name) && !name.endsWith(".changeset.json"))
         .map((name) => `${directory}/${name}`)
-        .sort((a, b) => {
-        const aTime = fs.statSync(a, { bigint: true }).mtimeNs;
-        const bTime = fs.statSync(b, { bigint: true }).mtimeNs;
-        return bTime > aTime ? 1 : bTime < aTime ? -1 : 0;
-    });
+        .map((file) => ({ file, key: sortKeyMtimeNs(file) }))
+        .filter((entry) => {
+        if (entry.key === undefined) {
+            skipped.push(basename(entry.file));
+            return false;
+        }
+        return true;
+    })
+        .sort((a, b) => (b.key > a.key ? 1 : b.key < a.key ? -1 : 0))
+        .map((entry) => entry.file);
+    if (skipped.length > 0) {
+        const shown = skipped.slice(0, 10).join(", ");
+        log(context, `rebuild-threads-index: skipped ${skipped.length} thread file(s) that vanished during the scan: ${shown}${skipped.length > 10 ? ", …" : ""}`);
+    }
     const rows = files.flatMap((file) => {
         const data = readJson(file);
         if (!data)

package/dist/main.js

@@ -70,6 +70,7 @@ import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
 import { isAuthError } from "./utils/auth-error.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
+import { formatPlanGateError, isPlanGateError, } from "./utils/plan-gate-error.js";
 import { refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
@@ -359,6 +360,13 @@ export function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies
         deps.stderr.write(`hq: ${err.message}\n`);
         deps.setExitCode(1);
     }
+    else if (isPlanGateError(err)) {
+        // hq-pro's plan denials are expected product limits, never a CLI crash.
+        // The shared vault client has already decoded and typed the small safe
+        // envelope; do not expose its raw body or retry a rejected creation.
+        deps.stderr.write(`hq: ${formatPlanGateError(err)}\n`);
+        deps.setExitCode(1);
+    }
     else if (isExpectedUserError(err)) {
         // HQ-CLI-6: a user-facing, client-caused error (a non-owner running
         // `hq integrations approve`, a stale queueId, a bad --args, an unknown

package/dist/utils/plan-gate-error.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A deliberate subscription denial returned by hq-pro. Keeping its structured
+ * fields on a typed error lets the CLI boundary render one safe, consistent
+ * message instead of every command parsing and printing a server response.
+ */
+export type PlanGateCode = "PLAN_LIMIT_EXCEEDED" | "PLAN_REQUIRED";
+export interface PlanGateDetails {
+    resource?: string;
+    used?: number;
+    limit?: number;
+    upgradeUrl?: string;
+}
+export declare class PlanGateError extends Error {
+    readonly code: PlanGateCode;
+    readonly details: PlanGateDetails;
+    constructor(code: PlanGateCode, details: PlanGateDetails);
+}
+export declare function isPlanGateError(err: unknown): err is PlanGateError;
+export declare function formatPlanGateError(err: PlanGateError): string;
+/** Decode an already-read JSON envelope from either shared HTTP client. */
+export declare function planGateErrorFromPayload(status: number, body: unknown): PlanGateError | null;
+/**
+ * Decode only the two deliberate plan-gate envelopes. Malformed, unrelated,
+ * or non-402 responses retain their existing command-specific handling.
+ */
+export declare function planGateErrorFromResponse(response: Response): Promise<{
+    error: PlanGateError | null;
+    response: Response;
+}>;
+//# sourceMappingURL=plan-gate-error.d.ts.map

package/dist/utils/plan-gate-error.js

@@ -0,0 +1,93 @@
+export class PlanGateError extends Error {
+    code;
+    details;
+    constructor(code, details) {
+        // Commands with their own expected-error boundary commonly print
+        // `err.message`. Keeping the friendly copy here means those boundaries
+        // retain the same plan-gate voice as main.ts without per-command handling.
+        super(formatPlanGateDetails(code, details));
+        this.code = code;
+        this.details = details;
+        this.name = "PlanGateError";
+    }
+}
+export function isPlanGateError(err) {
+    return err instanceof PlanGateError;
+}
+/** Plain, stable CLI copy for plan-gated resource creation. */
+function formatPlanGateDetails(code, details) {
+    const existingResourcesNote = "Existing resources will keep working.";
+    if (code === "PLAN_LIMIT_EXCEEDED" &&
+        typeof details.resource === "string" &&
+        typeof details.used === "number" &&
+        typeof details.limit === "number") {
+        const upgrade = typeof details.upgradeUrl === "string"
+            ? `Upgrade to HQ Team ($500/mo) to remove limits: ${details.upgradeUrl}`
+            : "Upgrade to HQ Team ($500/mo) to remove limits.";
+        return [
+            `Free plan limit reached: ${details.resource} ${details.used}/${details.limit} used.`,
+            upgrade,
+            existingResourcesNote,
+        ].join("\n");
+    }
+    const upgrade = typeof details.upgradeUrl === "string"
+        ? `Upgrade to HQ Team ($500/mo) to remove limits: ${details.upgradeUrl}`
+        : "Upgrade to HQ Team ($500/mo) to remove limits.";
+    return [
+        "HQ Team plan required for this feature.",
+        upgrade,
+        existingResourcesNote,
+    ].join("\n");
+}
+export function formatPlanGateError(err) {
+    return formatPlanGateDetails(err.code, err.details);
+}
+/** Decode an already-read JSON envelope from either shared HTTP client. */
+export function planGateErrorFromPayload(status, body) {
+    if (status !== 402 || !body || typeof body !== "object")
+        return null;
+    const payload = body;
+    if (payload.code !== "PLAN_LIMIT_EXCEEDED" && payload.code !== "PLAN_REQUIRED") {
+        return null;
+    }
+    return new PlanGateError(payload.code, {
+        ...(typeof payload.resource === "string" ? { resource: payload.resource } : {}),
+        ...(typeof payload.used === "number" ? { used: payload.used } : {}),
+        ...(typeof payload.limit === "number" ? { limit: payload.limit } : {}),
+        ...(typeof payload.upgradeUrl === "string" ? { upgradeUrl: payload.upgradeUrl } : {}),
+    });
+}
+/**
+ * Decode only the two deliberate plan-gate envelopes. Malformed, unrelated,
+ * or non-402 responses retain their existing command-specific handling.
+ */
+export async function planGateErrorFromResponse(response) {
+    // Leave every non-402 response untouched for its command-specific handler.
+    // A non-plan 402 is buffered and re-wrapped below so its useful error
+    // payload remains available to the existing command-specific handler.
+    if (response.status !== 402)
+        return { error: null, response };
+    let buffer;
+    try {
+        buffer = await response.arrayBuffer();
+    }
+    catch {
+        return { error: null, response };
+    }
+    let body = null;
+    try {
+        body = JSON.parse(new TextDecoder().decode(buffer));
+    }
+    catch {
+        // Preserve the original non-JSON 402 body below for its existing handler.
+    }
+    return {
+        error: planGateErrorFromPayload(response.status, body),
+        response: new Response(buffer, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        }),
+    };
+}
+//# sourceMappingURL=plan-gate-error.js.map

package/dist/utils/vault-api.js

@@ -4,6 +4,7 @@ import { AuthError } from './auth-error.js';
 import { CompanySelectionError } from './company-selection-error.js';
 import { recordPlanLimitStatus } from '../lib/plan-limit-nag.js';
 import { networkTransportErrorCode } from './network-transport-error.js';
+import { planGateErrorFromResponse } from './plan-gate-error.js';
 /**
  * Identity / company resolution lookups must never hang forever. These small
  * GETs run BEFORE a command does its real work (e.g. `hq secrets env` resolves
@@ -183,7 +184,13 @@ export async function vaultApiFetch(opts) {
             level: "warning",
             data: { url: safeUrl, status: response.status },
         });
-        return response;
+        // A plan gate is a normal, user-actionable denial. Decode it at the one
+        // shared HTTP seam so every resource-creation command reaches main.ts's
+        // friendly renderer without duplicating response parsing or retrying.
+        const planGate = await planGateErrorFromResponse(response);
+        if (planGate.error)
+            throw planGate.error;
+        return planGate.response;
     }
     return peekPlanLimitStatus(response);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.100.0",
+  "version": "5.101.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -29,7 +29,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "^6.14.50",
+    "@indigoai-us/hq-cloud": "~6.15.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",