@indigoai-us/hq-cli 5.99.3 → 5.101.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [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
+
+- `hq core checkpoint` now ends every non-dry-run checkpoint — real writes and
+  `--idle` alike — with a REMINDER line telling the calling agent that the
+  checkpoint is invisible bookkeeping, not the user-facing reply, and that any
+  substance not yet reported to the user must be delivered before the turn ends
+  (#374). The reminder is emitted even when sibling startup fails, and the
+  bundled Stop-gate prompt was reworded to prescribe the same reply-first
+  ordering. Machine-parsed outputs (`--dry-run` JSON, `--gate-probe`) are
+  unchanged.
+
 ## [5.99.3] — 2026-08-13
 
 ### Fixed

package/assets/scaffold/core/scripts/checkpoint-stop-gate.sh

@@ -327,7 +327,7 @@ set -uo pipefail
 
   # Built with printf rather than concatenation so the session id can appear in
   # both commands without re-splitting the message into fragments.
-  reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. If you owe them anything — a result, a link, an answer, a status — say it in the reply as usual. The checkpoint is invisible to them and is NOT a message to them; running it does not count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nSo: finish whatever you owe the user in the reply first, then run the checkpoint as the FINAL action of the turn and end the turn immediately after it — no further commentary once the command has run.\n\n  hq core checkpoint --session-id %s --trigger stop-gate --summary "<what changed, in one line>" [--file <path>] [--decision "<choice and why>"] [--learning "<reusable rule>"] [--next "<outstanding step>"]\n\nOnly --summary is required, and the repeatable flags are what the sibling uses to enrich the record, distil policies and update the indexes — a bare summary gives it almost nothing to work with. Write them as machine record, not prose for the user, and pass each one that genuinely applies:\n  --file      every path you created or modified this turn\n  --decision  a choice you made that a reader would otherwise have to reverse-engineer\n  --learning  a rule that changes how someone acts next time, not a restatement of what just happened\n  --next      work that is genuinely still outstanding\nOmit a flag rather than padding it: an empty or invented learning is worse than none.\n\nIf this turn only read or inspected things and changed no state, the correct call instead is:\n\n  hq core checkpoint --session-id %s --idle' "$session_id" "$session_id")"
+  reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. If you owe them anything — a result, a link, an answer, a status — say it in the reply as usual. The checkpoint is invisible to them and is NOT a message to them; running it does not count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nSo: finish whatever you owe the user in the reply first, then run the checkpoint as the FINAL action of the turn and end the turn immediately after it. The checkpoint output ends with a REMINDER restating this contract: if it catches you having skipped the user-facing reply, deliver that overdue reply — nothing else — and then end the turn; otherwise add no commentary after the command.\n\n  hq core checkpoint --session-id %s --trigger stop-gate --summary "<what changed, in one line>" [--file <path>] [--decision "<choice and why>"] [--learning "<reusable rule>"] [--next "<outstanding step>"]\n\nOnly --summary is required, and the repeatable flags are what the sibling uses to enrich the record, distil policies and update the indexes — a bare summary gives it almost nothing to work with. Write them as machine record, not prose for the user, and pass each one that genuinely applies:\n  --file      every path you created or modified this turn\n  --decision  a choice you made that a reader would otherwise have to reverse-engineer\n  --learning  a rule that changes how someone acts next time, not a restatement of what just happened\n  --next      work that is genuinely still outstanding\nOmit a flag rather than padding it: an empty or invented learning is worse than none.\n\nIf this turn only read or inspected things and changed no state, the correct call instead is:\n\n  hq core checkpoint --session-id %s --idle' "$session_id" "$session_id")"
 
   # Codex surfaces a blocked Stop reason as a synthetic user prompt. Preserve
   # the actionable instruction out-of-band, then use the stable marker covered

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/core-checkpoint.d.ts

@@ -9,6 +9,19 @@
 import { Command } from "commander";
 type Backend = "claude" | "codex" | "grok" | "none";
 type SpawnableBackend = Exclude<Backend, "none">;
+/**
+ * Printed after every non-dry-run checkpoint, real or --idle. Agents were
+ * treating the checkpoint call as the end of the turn, leaving their actual
+ * findings only in the checkpoint payload — which the user never sees. This
+ * line rides the command output (the one channel guaranteed to reach the
+ * calling agent) to force the user-facing reply. Deliberately conditional so
+ * it composes with the Stop-gate prompt's "reply first, checkpoint last, then
+ * end the turn" ordering: an agent that already replied is told to end the
+ * turn, not to add commentary. Mirrors the hq-core policies
+ * `checkpoint-is-bookkeeping-not-user-communication` and
+ * `checkpoint-is-not-the-user-report`.
+ */
+export declare const CHECKPOINT_REPLY_REMINDER: string;
 /**
  * Kept in TypeScript rather than in a bundled asset: it is an instruction to
  * a locally-installed agent, not a scaffold script that should be packaged.

package/dist/commands/core-checkpoint.js

@@ -40,6 +40,23 @@ const SIBLING_LOCK_TTL_MS = 60 * 60 * 1000;
 const MAX_PENDING_PAYLOADS = 50;
 class CheckpointUsageError extends Error {
 }
+/**
+ * Printed after every non-dry-run checkpoint, real or --idle. Agents were
+ * treating the checkpoint call as the end of the turn, leaving their actual
+ * findings only in the checkpoint payload — which the user never sees. This
+ * line rides the command output (the one channel guaranteed to reach the
+ * calling agent) to force the user-facing reply. Deliberately conditional so
+ * it composes with the Stop-gate prompt's "reply first, checkpoint last, then
+ * end the turn" ordering: an agent that already replied is told to end the
+ * turn, not to add commentary. Mirrors the hq-core policies
+ * `checkpoint-is-bookkeeping-not-user-communication` and
+ * `checkpoint-is-not-the-user-report`.
+ */
+export const CHECKPOINT_REPLY_REMINDER = "checkpoint: REMINDER — this checkpoint is invisible bookkeeping; the user never sees it " +
+    "and it does NOT count as your reply. If your reply to the user already contains " +
+    "everything of substance from this turn, end the turn now. If anything — results, " +
+    "findings, decisions, state changes, anything awaiting their input — exists only in this " +
+    "checkpoint or your head, deliver it to the user in plain language before ending the turn.";
 function printResult(line) {
     process.stdout.write(`${line}\n`);
 }
@@ -801,6 +818,9 @@ function runCheckpoint(options, command, group) {
         }
         writeStamps(liveRoot, resolveSessionId(options, command, readPayload(options.payload)));
         printResult("checkpoint: idle (nothing to record)");
+        // An idle turn persisted nothing, but a read-only turn can still have
+        // produced substantive findings the user has not been told about.
+        printResult(CHECKPOINT_REPLY_REMINDER);
         return;
     }
     const payload = readPayload(options.payload);
@@ -860,13 +880,22 @@ function runCheckpoint(options, command, group) {
     fs.writeFileSync(threadPath, `${JSON.stringify(thread, null, 2)}\n`);
     writeStamps(liveRoot, input.sessionId);
     printResult(`checkpoint: ${relativeThreadPath}`);
-    if (options.agent === false)
-        return;
-    if (backend === "none") {
-        printResult("checkpoint: sibling disabled (backend none)");
-        return;
+    // finally: the thread is already written at this point, so the agent must
+    // get the reminder even when sibling startup throws (e.g. an explicitly
+    // requested backend that is not installed).
+    try {
+        if (options.agent !== false) {
+            if (backend === "none") {
+                printResult("checkpoint: sibling disabled (backend none)");
+            }
+            else {
+                startSibling(liveRoot, input, threadPath, backend);
+            }
+        }
+    }
+    finally {
+        printResult(CHECKPOINT_REPLY_REMINDER);
     }
-    startSibling(liveRoot, input, threadPath, backend);
 }
 function reportUsage(error) {
     printError("Usage: hq core checkpoint --summary <text> [options]");

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/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.99.3",
+  "version": "5.101.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {