@indigoai-us/hq-cli 5.345.142 → 5.345.144

package/dist/lib/plan-limit-nag.d.ts

@@ -32,6 +32,7 @@
  * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1` silences all
  * three surfaces, the threshold notice included.
  */
+import { type PricingPlan } from "./billing/usage-only.js";
 export declare const PLAN_LIMIT_UPGRADE_URL = "https://hq.computer/billing/upgrade";
 /**
  * Cadence of the over-limit per-turn line (US-036). Was once a day; the nag
@@ -67,11 +68,6 @@ export interface PlanLimitThresholdCrossing {
     used: number;
     limit: number;
 }
-/**
- * Record plan-limit status from a decoded JSON response body.
- * Never throws. Overwrites the last-seen cell when a well-formed
- * `planLimits` object is present; ignores malformed / absent payloads.
- */
 export declare function recordPlanLimitStatus(body: unknown, opts?: {
     write?: (s: string) => void;
     statePath?: string;
@@ -104,7 +100,9 @@ export declare const INDIVIDUAL_PRICE_LABEL = "$50/mo";
  * own checkout target; an older hq-pro sends none, and the line then names the
  * plan without a link rather than inventing one.
  */
-export declare function renderPersonalPlanFeatureNotice(feature: string, upgradeUrl?: string | null): string;
+export declare function renderPersonalPlanFeatureNotice(feature: string, upgradeUrl?: string | null, opts?: {
+    pricingPlan?: PricingPlan | null;
+}): string;
 /**
  * One line per crossing.
  *

package/dist/lib/plan-limit-nag.js

@@ -39,6 +39,7 @@ import * as path from "node:path";
 import { resolveProcessFlagCompanyContext } from "./flag-registry.js";
 import { isCliLimitResourceKind, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
 import { planLimitUpgradeFallbackUrl, selectPlanLimitUpgradeUrl, } from "./billing/plan-limit-upgrade-url.js";
+import { isUsageOnly, pricingPlanFromBody, usageOnlyPersonalFeatureNotice, } from "./billing/usage-only.js";
 export const PLAN_LIMIT_UPGRADE_URL = "https://hq.computer/billing/upgrade";
 /**
  * Cadence of the over-limit per-turn line (US-036). Was once a day; the nag
@@ -220,8 +221,21 @@ function parseThresholdCrossings(body) {
  * Never throws. Overwrites the last-seen cell when a well-formed
  * `planLimits` object is present; ignores malformed / absent payloads.
  */
+/** Set once a body in this process says the account is on usage pricing. */
+let usageOnlySeen = false;
 export function recordPlanLimitStatus(body, opts = {}) {
     try {
+        // Usage pricing (US-012): a body that says the account is on usage
+        // pricing carries no Starter caps to nag about. Drop any earlier Starter
+        // status so the completion nag stays silent too.
+        // The flag is sticky for the process: a later 2xx body that carries
+        // `planLimits` without `pricingPlan` (an older route) must not bring the
+        // Starter nag back for the same command.
+        if (usageOnlySeen || isUsageOnly(pricingPlanFromBody(body))) {
+            usageOnlySeen = true;
+            lastSeen = null;
+            return;
+        }
         const status = parsePlanLimits(body);
         const crossings = parseThresholdCrossings(body);
         let resolvedUpgradeUrl = null;
@@ -384,8 +398,11 @@ const PERSONAL_FEATURE_LABELS = {
  * own checkout target; an older hq-pro sends none, and the line then names the
  * plan without a link rather than inventing one.
  */
-export function renderPersonalPlanFeatureNotice(feature, upgradeUrl) {
+export function renderPersonalPlanFeatureNotice(feature, upgradeUrl, opts = {}) {
     const label = PERSONAL_FEATURE_LABELS[feature] ?? feature;
+    // A person on usage pricing has no Individual plan to buy (US-012).
+    if (isUsageOnly(opts.pricingPlan))
+        return usageOnlyPersonalFeatureNotice(label);
     const headline = `${label} is included with the HQ ${INDIVIDUAL_PLAN_NAME} plan (${INDIVIDUAL_PRICE_LABEL}).`;
     const action = typeof upgradeUrl === "string" && upgradeUrl.trim().length > 0
         ? `Upgrade: ${upgradeUrl.trim()}`
@@ -517,6 +534,7 @@ export function emitPlanLimitNag(opts = {}) {
 /** Test-only helper — clears last-seen status and session dedupe flags. */
 export function _resetForTests() {
     lastSeen = null;
+    usageOnlySeen = false;
     warningShownThisSession = false;
     overShownThisSession = false;
     thresholdsShownThisSession.clear();

package/dist/lib/provider-launcher.d.ts

@@ -8,4 +8,26 @@ export interface ProviderLauncherDependencies {
 }
 export declare function providerLoginGuidance(provider: ProviderName, output: string): string | null;
 export declare function runProviderLauncher(providerValue: string, args: readonly string[], dependencies?: ProviderLauncherDependencies): Promise<number>;
+export interface ProviderCaptureOptions {
+    spawn?: typeof nodeSpawn;
+    cwd?: string;
+    /** Kill the child and report `timedOut` after this many milliseconds. */
+    timeoutMs: number;
+}
+export type ProviderCaptureResult = {
+    kind: "ok";
+    stdout: string;
+} | {
+    kind: "not-installed";
+} | {
+    kind: "not-signed-in";
+    guidance: string;
+} | {
+    kind: "timed-out";
+} | {
+    kind: "error";
+    code: number;
+    stderrTail: string;
+};
+export declare function captureProviderRun(provider: "claude", args: readonly string[], options: ProviderCaptureOptions): Promise<ProviderCaptureResult>;
 //# sourceMappingURL=provider-launcher.d.ts.map

package/dist/lib/provider-launcher.js

@@ -53,6 +53,71 @@ export async function runProviderLauncher(providerValue, args, dependencies = {}
         });
     });
 }
+const CAPTURE_LIMIT = 1024 * 1024;
+/**
+ * Run a noninteractive Claude Code command (`claude -p ...`) and capture its
+ * output instead of streaming it. stdin is closed so the child never waits on
+ * the terminal, and the run is bounded by `timeoutMs`. Never throws.
+ */
+const KILL_GRACE_MS = 5_000;
+export async function captureProviderRun(provider, args, options) {
+    if (!args.some((arg) => arg === "-p" || arg === "--print")) {
+        throw new Error("captureProviderRun needs a noninteractive Claude Code command (-p or --print).");
+    }
+    let child;
+    try {
+        child = (options.spawn ?? nodeSpawn)(provider, [...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+            ...(options.cwd ? { cwd: options.cwd } : {}),
+        });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return { kind: "not-installed" };
+        return { kind: "error", code: 1, stderrTail: err.message };
+    }
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+        stdout = `${stdout}${String(chunk)}`.slice(-CAPTURE_LIMIT);
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr = `${stderr}${String(chunk)}`.slice(-16_384);
+    });
+    return await new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            const hardKill = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill("SIGKILL");
+            }, KILL_GRACE_MS);
+            hardKill.unref();
+            child.unref();
+            finish({ kind: "timed-out" });
+        }, options.timeoutMs);
+        child.once("error", (err) => {
+            finish(err.code === "ENOENT" ? { kind: "not-installed" } : { kind: "error", code: 1, stderrTail: err.message });
+        });
+        child.once("close", (code) => {
+            const guidance = providerLoginGuidance(provider, `${stdout.slice(-16_384)}\n${stderr}`);
+            if (guidance)
+                return finish({ kind: "not-signed-in", guidance });
+            if (code === 0)
+                return finish({ kind: "ok", stdout });
+            finish({ kind: "error", code: code ?? 1, stderrTail: stderr.trim().slice(-500) });
+        });
+    });
+}
 function write(stream, message) {
     (stream ?? process.stderr).write(message);
 }

package/dist/lib/search-index/index.d.ts

@@ -544,6 +544,8 @@ export type SearchCollection = {
     mask: string;
     context: string;
 };
+/** Mask of the per-company `<co>-assets` collection: library asset placeholders. */
+export declare const ASSET_COLLECTION_MASK = "**/*.hqcloud";
 /** Derive the local qmd collection policy for one HQ tree. */
 export declare function deriveCollections(hqRoot: string): SearchCollection[];
 export type ReconcileCollectionsOptions = {

package/dist/lib/search-index/index.js

@@ -1353,6 +1353,24 @@ function containsProjectSource(directory) {
     }
     return false;
 }
+/** Mask of the per-company `<co>-assets` collection: library asset placeholders. */
+export const ASSET_COLLECTION_MASK = '**/*.hqcloud';
+const ASSET_SCAN_SKIP_DIRS = new Set(['.git', 'node_modules']);
+function containsAssetPlaceholder(directory) {
+    if (!fs.existsSync(directory))
+        return false;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const child = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!ASSET_SCAN_SKIP_DIRS.has(entry.name) && containsAssetPlaceholder(child))
+                return true;
+        }
+        else if (entry.isFile() && entry.name.endsWith('.hqcloud') && entry.name !== '.hqcloud') {
+            return true;
+        }
+    }
+    return false;
+}
 /** Derive the local qmd collection policy for one HQ tree. */
 export function deriveCollections(hqRoot) {
     const root = path.resolve(hqRoot);
@@ -1385,6 +1403,22 @@ export function deriveCollections(hqRoot) {
             context: `Project PRDs and documentation for ${entry.name}.`,
         });
     }
+    // Library asset placeholders can sit anywhere under a company (offload
+    // replaces a file in place), so the collection is rooted at the company and
+    // its mask admits only `.hqcloud` files. A separate collection, rather than
+    // widening the knowledge/projects masks, because reconcileCollections adds
+    // missing collections but never rewrites an existing collection's mask.
+    for (const entry of companies) {
+        const companyDir = path.join(companiesDir, entry.name);
+        if (!containsAssetPlaceholder(companyDir))
+            continue;
+        collections.push({
+            name: `${entry.name}-assets`,
+            path: companyDir,
+            mask: ASSET_COLLECTION_MASK,
+            context: `Library asset placeholders (.hqcloud) for ${entry.name}.`,
+        });
+    }
     const personalKnowledge = path.join(root, 'personal', 'knowledge');
     if (containsIndexedMarkdown(personalKnowledge)) {
         collections.push({

package/dist/lib/search-index/max-doc-bytes.d.ts

@@ -101,7 +101,8 @@ export declare function resolveIndexMaxDocBytes(opts?: {
 /**
  * Extensions a qmd mask selects, lowercased and without the dot.
  *
- * HQ registers exactly two mask shapes today (see `deriveCollections`), but an
+ * HQ registers single-extension (`**\/*.md`, `**\/*.hqcloud`) and brace-list
+ * (`**\/*.{md,json}`) masks today (see `deriveCollections`), but an
  * operator's own collection may carry anything. An unrecognised mask returns
  * `null`, meaning "match every file" — the cap then applies to the whole
  * collection, which is the safe direction: we may ignore a file qmd would not

package/dist/lib/search-index/max-doc-bytes.js

@@ -177,7 +177,8 @@ function parseNonNegativeInt(value) {
 /**
  * Extensions a qmd mask selects, lowercased and without the dot.
  *
- * HQ registers exactly two mask shapes today (see `deriveCollections`), but an
+ * HQ registers single-extension (`**\/*.md`, `**\/*.hqcloud`) and brace-list
+ * (`**\/*.{md,json}`) masks today (see `deriveCollections`), but an
  * operator's own collection may carry anything. An unrecognised mask returns
  * `null`, meaning "match every file" — the cap then applies to the whole
  * collection, which is the safe direction: we may ignore a file qmd would not

package/dist/main.d.ts

@@ -7,6 +7,8 @@ import "./node-network-compat.js";
 import { Sentry } from "./sentry.js";
 export { handleStreamError } from "./stream-error-boundary.js";
 export type { StreamErrorDependencies } from "./stream-error-boundary.js";
+import { type PlanGateError } from "./utils/plan-gate-error.js";
+import { type PricingPlan } from "./lib/billing/usage-only.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
 /**
  * Total time one CLI invocation may await foreground network work. This spans
@@ -43,7 +45,14 @@ export type TopLevelErrorDependencies = {
     ask?: (question: string) => Promise<string>;
     openUrl?: (url: string) => Promise<void>;
     upgradeToTeam?: typeof upgradeToTeam;
+    /**
+     * Usage pricing (US-012): resolve the account's pricing plan for a plan gate
+     * whose 402 body did not carry one. Absent = use the body only.
+     */
+    resolvePricingPlan?: (planGate: PlanGateError) => Promise<PricingPlan | null>;
 };
+/** Production resolver: membership row / usage-limits / summary, never interactive. */
+export declare function resolvePlanGatePricingPlan(planGate: PlanGateError): Promise<PricingPlan | null>;
 export declare const MAX_OWN_DIST_RELATIVE_PATH_BYTES = 256;
 /** Return a bounded path only when targetPath is beneath packageRoot/dist. */
 export declare function relativeOwnDistModulePath(packageRootPath: string, targetPath: string): string | undefined;

package/dist/main.js

@@ -40,7 +40,8 @@ import { browserLoginAbandonedMessage } from "./utils/browser-login-abandoned.js
 import { callbackPortBusyMessage, DEFAULT_CALLBACK_PORT } from "./utils/callback-port-busy.js";
 import { DEFAULT_COGNITO, isMachineIdentity, loadMachineCachedTokens, } from "./utils/cognito-session.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
-import { canOfferTeamUpgrade, formatPlanGateError, offerTeamUpgrade, offerUpgradeLink, planGateErrorFromVaultError, } from "./utils/plan-gate-error.js";
+import { canOfferTeamUpgrade, formatPlanGateError, offerTeamUpgrade, offerUpgradeLink, planGateErrorFromVaultError, withPricingPlan, } from "./utils/plan-gate-error.js";
+import { isUsageOnly, resolveCompanyPricingPlan, resolvePersonPricingPlan, } from "./lib/billing/usage-only.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
 import { printCachedVersionNudge, printVersionAndNudge, refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
 import { enforceVersionGate, getVersionGatePhase, isLocalDependencyInstall, resolveRunningInstall, shouldSkipGate, } from "./utils/version-gate.js";
@@ -375,8 +376,19 @@ export async function runCli() {
         }
     }
 }
+/** Production resolver: membership row / usage-limits / summary, never interactive. */
+export async function resolvePlanGatePricingPlan(planGate) {
+    if (planGate.code === "PERSONAL_PLAN_REQUIRED")
+        return resolvePersonPricingPlan({ timeoutMs: 3000 });
+    const companyUid = planGate.details.companyUid;
+    if (typeof companyUid === "string" && /^cmp_[A-Za-z0-9_-]+$/.test(companyUid)) {
+        return resolveCompanyPricingPlan(companyUid, { timeoutMs: 3000 });
+    }
+    return null;
+}
 const defaultTopLevelErrorDependencies = {
     sentry: Sentry,
+    resolvePricingPlan: resolvePlanGatePricingPlan,
     stderr: process.stderr,
     setExitCode: (code) => {
         process.exitCode = code;
@@ -562,7 +574,11 @@ function ownDistModuleMissingCaptureContext(err) {
 export async function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies) {
     // A typed plan gate, or an hq-cloud vault error carrying a plan-limit
     // refusal (402 / PLAN_LIMIT_* from a sync, share or skill upload).
-    const planGate = planGateErrorFromVaultError(err);
+    const decodedPlanGate = planGateErrorFromVaultError(err);
+    const planGate = decodedPlanGate && !decodedPlanGate.details.pricingPlan && deps.resolvePricingPlan
+        ? withPricingPlan(decodedPlanGate, await deps.resolvePricingPlan(decodedPlanGate).catch(() => null))
+        : decodedPlanGate;
+    const usageOnlyGate = isUsageOnly(planGate?.details.pricingPlan);
     // 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
@@ -654,7 +670,8 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             ? queueCliLimitNoticeExposure(planGate.details.resource, "refusal", planGate.details.companyUid)
             : null;
         deps.setExitCode(1);
-        if (interactive && planGate.details.upgradeUrl) {
+        // A usage-only account has no plan to buy: no checkout or upgrade offer.
+        if (interactive && planGate.details.upgradeUrl && !usageOnlyGate) {
             const companyUid = planGate.details.companyUid;
             const isCompanyWorkforceCheckout = typeof companyUid === "string" &&
                 /^cmp_[A-Za-z0-9_-]+$/.test(companyUid) &&

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

@@ -15,14 +15,29 @@
  *   3. `hq billing checkout` (see commands/billing.ts) reuses `mintPaymentLink`
  *      to hand out the same link proactively.
  *
- * Prices mirror the console's authoritative constants
+ * Legacy prices mirror the console's authoritative constants
  * (hq-console `src/lib/billing-pricing.ts`): amounts are in the smallest
- * currency unit (US cents) to match Stripe's wire shape.
+ * currency unit (US cents) to match Stripe's wire shape. They apply to
+ * accounts on the plans that existed before usage pricing.
+ *
+ * Usage pricing (US-012): boxes are quoted by size from the usage card
+ * (`src/lib/billing/usage-card.ts`, `GET /v1/pricing` with a bundled
+ * fallback): small t3.small, medium t3.medium, large t3.large, xlarge
+ * t3.xlarge. Use {@link usageBoxQuotes} / {@link usageBoxQuoteCents}, never
+ * the legacy constants, for a usage-only account.
  */
-/** Per-Agent monthly list price, in cents ($100.00 / agent / month). */
+import { type UsageCard } from "../lib/billing/usage-card.js";
+/** Legacy per-Agent monthly list price, in cents ($100.00 / agent / month). */
 export declare const AGENT_PRICE_CENTS = 10000;
-/** Per-Outpost monthly list price, in cents ($80.00 / Outpost / month). */
+/** Legacy per-Outpost monthly list price, in cents ($80.00 / Outpost / month). */
 export declare const OUTPOST_PRICE_CENTS = 8000;
+/** Usage-pricing box sizes, in card order ("small (t3.small) $100/month, ..."). */
+export declare function usageBoxQuotes(card?: UsageCard): string;
+/**
+ * Monthly price of one usage-pricing box, in cents, by size or instance type.
+ * Null for a size the card does not list.
+ */
+export declare function usageBoxQuoteCents(sizeOrInstanceType: string, card?: UsageCard): number | null;
 /** Render a cents amount as a `$X.YZ` USD string. */
 export declare function formatUsd(cents: number): string;
 /**

package/dist/utils/billing-gate.js

@@ -15,16 +15,37 @@
  *   3. `hq billing checkout` (see commands/billing.ts) reuses `mintPaymentLink`
  *      to hand out the same link proactively.
  *
- * Prices mirror the console's authoritative constants
+ * Legacy prices mirror the console's authoritative constants
  * (hq-console `src/lib/billing-pricing.ts`): amounts are in the smallest
- * currency unit (US cents) to match Stripe's wire shape.
+ * currency unit (US cents) to match Stripe's wire shape. They apply to
+ * accounts on the plans that existed before usage pricing.
+ *
+ * Usage pricing (US-012): boxes are quoted by size from the usage card
+ * (`src/lib/billing/usage-card.ts`, `GET /v1/pricing` with a bundled
+ * fallback): small t3.small, medium t3.medium, large t3.large, xlarge
+ * t3.xlarge. Use {@link usageBoxQuotes} / {@link usageBoxQuoteCents}, never
+ * the legacy constants, for a usage-only account.
  */
 import chalk from "chalk";
 import { vaultApiFetch } from "./vault-api.js";
-/** Per-Agent monthly list price, in cents ($100.00 / agent / month). */
+import { BUNDLED_USAGE_CARD, formatBoxQuotes, } from "../lib/billing/usage-card.js";
+/** Legacy per-Agent monthly list price, in cents ($100.00 / agent / month). */
 export const AGENT_PRICE_CENTS = 10_000;
-/** Per-Outpost monthly list price, in cents ($80.00 / Outpost / month). */
+/** Legacy per-Outpost monthly list price, in cents ($80.00 / Outpost / month). */
 export const OUTPOST_PRICE_CENTS = 8_000;
+/** Usage-pricing box sizes, in card order ("small (t3.small) $100/month, ..."). */
+export function usageBoxQuotes(card = BUNDLED_USAGE_CARD) {
+    return formatBoxQuotes(card);
+}
+/**
+ * Monthly price of one usage-pricing box, in cents, by size or instance type.
+ * Null for a size the card does not list.
+ */
+export function usageBoxQuoteCents(sizeOrInstanceType, card = BUNDLED_USAGE_CARD) {
+    const ref = sizeOrInstanceType.trim().toLowerCase();
+    const box = card.boxes.find((b) => b.size.toLowerCase() === ref || b.instanceType.toLowerCase() === ref);
+    return box ? Math.round(box.monthlyUsd * 100) : null;
+}
 /** Render a cents amount as a `$X.YZ` USD string. */
 export function formatUsd(cents) {
     return `$${(Math.max(0, Math.round(cents)) / 100).toFixed(2)}`;

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

@@ -1,4 +1,5 @@
 import { type PlanLimitFreeMonth } from "../lib/billing/free-month.js";
+import { type PricingPlan } from "../lib/billing/usage-only.js";
 export type PlanGateCode = "PLAN_LIMIT_EXCEEDED" | "PLAN_REQUIRED" | "MEETING_PLAN_REQUIRED"
 /** A PERSONAL scope asked for a feature the paid Individual plan includes. */
  | "PERSONAL_PLAN_REQUIRED"
@@ -27,7 +28,16 @@ export interface PlanGateDetails {
     fixOptions?: Record<string, number>;
     /** Hard-stop 402: the free-month offer, present only when it stands. */
     freeMonth?: PlanLimitFreeMonth;
+    /**
+     * Usage pricing (US-012): from the 402 body, or attached by the caller from
+     * /membership/me, usage-limits or the billing summary. `"usage-only"`
+     * renders no free month, Starter, Workforce or Individual copy and no plan
+     * upgrade link. Absent keeps the legacy copy.
+     */
+    pricingPlan?: PricingPlan;
 }
+/** Copy a plan gate with the caller's pricing plan attached. */
+export declare function withPricingPlan(err: PlanGateError, pricingPlan: PricingPlan | null | undefined): PlanGateError;
 /** One renderer for server-selected upgrade links across CLI plan refusals. */
 export declare function formatUpgradeRefusal(reason: string, upgradeUrl: string | undefined, options?: {
     urlOnly?: boolean;

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

@@ -6,6 +6,48 @@
 import { PLAN_LIMIT_DIMENSION_LABELS, renderPersonalPlanFeatureNotice, } from "../lib/plan-limit-nag.js";
 import { withCliLimitEntrySurface } from "../lib/billing/plan-limit-upgrade-url.js";
 import { parseFreeMonth, } from "../lib/billing/free-month.js";
+import { isUsageOnly, pricingPlanFromBody, usageOnlyCardRequiredLines, USAGE_PRICING_POINTER, } from "../lib/billing/usage-only.js";
+/** Legacy plan names and prices a usage-only account must never be shown. */
+const LEGACY_PLAN_COPY = /Starter|Workforce|Individual|\$500|\$50\b|free month|upgrade/i;
+/** Copy a plan gate with the caller's pricing plan attached. */
+export function withPricingPlan(err, pricingPlan) {
+    if (!pricingPlan || err.details.pricingPlan === pricingPlan)
+        return err;
+    return new PlanGateError(err.code, { ...err.details, pricingPlan });
+}
+/** The usage-only rendering of a plan gate. Never names a legacy plan. */
+function usageOnlyPlanGateReason(code, details) {
+    switch (code) {
+        case "PERSONAL_PLAN_REQUIRED":
+            return renderPersonalPlanFeatureNotice(details.feature ?? "this feature", null, {
+                pricingPlan: "usage-only",
+            });
+        case "MEETING_PLAN_REQUIRED":
+            return usageOnlyCardRequiredLines("A meeting notetaker bot").join("\n");
+        case "BILLING_REQUIRED":
+            return usageOnlyCardRequiredLines("An external agent").join("\n");
+        case "PLAN_REQUIRED":
+            return usageOnlyCardRequiredLines("This feature").join("\n");
+        case "PLAN_LIMIT_EXCEEDED": {
+            const server = details.reason?.trim();
+            const head = server && !LEGACY_PLAN_COPY.test(server) ? server : "This account has reached a usage limit.";
+            const lines = [head];
+            for (const row of details.resources ?? []) {
+                lines.push(`  ${resourceLabel(row.resource)}: ` +
+                    `${formatResourceAmount(row.resource, row.used)} of ` +
+                    `${formatResourceAmount(row.resource, row.limit)} used.`);
+            }
+            const fixes = Object.entries(details.fixOptions ?? {}).map(([resource, target]) => `${resourceFixAction(resource)} to make room (the limit is ` +
+                `${formatResourceAmount(resource, target)}).`);
+            if (fixes.length > 0) {
+                lines.push("  Ways to sort it:");
+                fixes.forEach((fix, index) => lines.push(`    ${index + 1}. ${fix}`));
+            }
+            lines.push(USAGE_PRICING_POINTER);
+            return lines.join("\n");
+        }
+    }
+}
 const GIB = 1024 ** 3;
 const MIB = 1024 ** 2;
 const KIB = 1024;
@@ -75,6 +117,8 @@ function planLimitRefusalText(head, details) {
     return lines.join("\n");
 }
 function planGateReason(code, details) {
+    if (isUsageOnly(details.pricingPlan))
+        return usageOnlyPlanGateReason(code, details);
     if (code === "PLAN_LIMIT_EXCEEDED") {
         const head = details.reason?.trim()
             ? details.reason.trim()
@@ -143,6 +187,8 @@ export function companyUidFromPlanUpgradeUrl(value) {
     return match?.[1];
 }
 function formatPlanGateErrorText(code, details) {
+    if (isUsageOnly(details.pricingPlan))
+        return planGateReason(code, details);
     return formatUpgradeRefusal(planGateReason(code, details), details.upgradeUrl);
 }
 export class PlanGateError extends Error {
@@ -160,6 +206,9 @@ export function isPlanGateError(err) {
 }
 /** Plain, stable CLI copy for plan-gated resource creation. */
 export function formatPlanGateError(err, options = {}) {
+    // A usage-only account has no plan to upgrade to: no upgrade link.
+    if (isUsageOnly(err.details.pricingPlan))
+        return planGateReason(err.code, err.details);
     return formatUpgradeRefusal(planGateReason(err.code, err.details), err.details.upgradeUrl, options);
 }
 export function canOfferTeamUpgrade(argv = process.argv) {
@@ -229,6 +278,11 @@ export function planGateErrorFromPayload(status, body, companyUid) {
     if (status !== 402 || !body || typeof body !== "object")
         return null;
     const payload = body;
+    const decoded = decodePlanGatePayload(payload, companyUid);
+    const pricingPlan = pricingPlanFromBody(payload);
+    return decoded && pricingPlan ? withPricingPlan(decoded, pricingPlan) : decoded;
+}
+function decodePlanGatePayload(payload, companyUid) {
     // US-054: the personal feature denial. hq-pro identifies it with
     // `error: "plan_feature_unavailable"` plus `scope: "personal"`; both the
     // `scope` and `requiredPlan` fields are OPTIONAL on the wire, so an hq-pro

package/dist/utils/vault-api.js

@@ -172,7 +172,10 @@ function hasPlanLimitStatusPayload(body) {
     if (body === null || typeof body !== 'object' || Array.isArray(body)) {
         return false;
     }
-    return Object.hasOwn(body, 'planLimits') || Object.hasOwn(body, 'thresholdCrossings');
+    return (Object.hasOwn(body, 'planLimits') ||
+        Object.hasOwn(body, 'thresholdCrossings') ||
+        // Usage pricing (US-012): a usage-only body silences the Starter nag.
+        body.pricingPlan === 'usage-only');
 }
 /**
  * Map Cognito JWT paths onto parallel Bearer `hqk_` routes under `/v1/keys/…`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.142",
+  "version": "5.345.144",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -48,7 +48,7 @@
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
     "@aws-sdk/dsql-signer": "^3.1146.0",
-    "@indigoai-us/hq-cloud": "~6.18.77",
+    "@indigoai-us/hq-cloud": "~6.18.82",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@sentry/node": "^10.49.0",