@indigoai-us/hq-cli 5.248.0 → 5.249.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.249.0] — 2026-09-27
+
+### Fixed
+
+- Plan-limit notices prefer the current usage-limits upgrade URL and can use
+  the company console billing page as a default-off hq-flags fallback.
+
 ## [5.248.0] — 2026-09-27
 
 ### Changed

package/dist/commands/integrations-connect.d.ts

@@ -17,6 +17,8 @@
  * "key" but is really OAuth-protected still connects on the first try.
  */
 import { Command } from "commander";
+import { consoleOrigin } from "../utils/console-origin.js";
+export { consoleOrigin };
 import type { AdminConnection } from "./integrations-core.js";
 import { type InstallInput } from "./integrations-api.js";
 interface ConnectOptions {
@@ -57,19 +59,6 @@ interface ConnectTarget {
     /** Human label for prompts and success lines. */
     label: string;
 }
-/**
- * The console that fronts the control plane this CLI is pointed at.
- *
- * A handoff must land on the console for the SAME backend, because that
- * console starts its own OAuth flow against its own backend. Sending a staging
- * session to the production console would connect the app in the wrong place —
- * so when the control plane is overridden and its console cannot be derived,
- * return undefined and say so rather than guess a host.
- *
- * `HQ_CONSOLE_URL` is the explicit override; otherwise the console is the
- * control-plane host with its `hqapi.` prefix removed.
- */
-export declare function consoleOrigin(vaultApiUrl?: string): string | undefined;
 /**
  * The console's Integrations page for a company, the console root when the
  * caller never named one (a single-membership session resolves the company
@@ -95,5 +84,4 @@ export declare function bringYourOwnClientHandoff(target: ConnectTarget, opts: C
 export declare function googleClientTypeHint(clientId: string, authorizationUrl: string): string | null;
 export declare function findAlreadyConnected(connections: readonly AdminConnection[], app: string): AdminConnection | undefined;
 export declare function registerConnectCommands(integrations: Command): void;
-export {};
 //# sourceMappingURL=integrations-connect.d.ts.map

package/dist/commands/integrations-connect.js

@@ -18,7 +18,9 @@
  */
 import chalk from "chalk";
 import open from "open";
-import { DEFAULT_VAULT_API_URL, ensureCognitoIdToken, } from "../utils/cognito-session.js";
+import { ensureCognitoIdToken } from "../utils/cognito-session.js";
+import { consoleOrigin } from "../utils/console-origin.js";
+export { consoleOrigin };
 import { getCompanyUid } from "../utils/vault-api.js";
 import { redactSensitiveUrl, redactUrlsInText } from "../utils/redact-url.js";
 import { IntegrationsCliError, bareProvider, connectionDomain, fetchAdminSurface, printJson, revokedConnectionDetails, resolveConnection, } from "./integrations-core.js";
@@ -536,37 +538,6 @@ async function connectViaOAuth(token, companyUid, target, opts) {
         listener.close();
     }
 }
-const PRODUCTION_CONSOLE_ORIGIN = "https://hq.computer";
-const PRODUCTION_VAULT_API_HOST = "hqapi.hq.computer";
-/**
- * The console that fronts the control plane this CLI is pointed at.
- *
- * A handoff must land on the console for the SAME backend, because that
- * console starts its own OAuth flow against its own backend. Sending a staging
- * session to the production console would connect the app in the wrong place —
- * so when the control plane is overridden and its console cannot be derived,
- * return undefined and say so rather than guess a host.
- *
- * `HQ_CONSOLE_URL` is the explicit override; otherwise the console is the
- * control-plane host with its `hqapi.` prefix removed.
- */
-export function consoleOrigin(vaultApiUrl = DEFAULT_VAULT_API_URL) {
-    const explicit = process.env.HQ_CONSOLE_URL?.trim();
-    if (explicit)
-        return explicit.replace(/\/+$/, "");
-    let api;
-    try {
-        api = new URL(vaultApiUrl);
-    }
-    catch {
-        return undefined;
-    }
-    if (api.host === PRODUCTION_VAULT_API_HOST)
-        return PRODUCTION_CONSOLE_ORIGIN;
-    if (!api.hostname.startsWith("hqapi."))
-        return undefined;
-    return `${api.protocol}//${api.host.slice("hqapi.".length)}`;
-}
 /**
  * The console's Integrations page for a company, the console root when the
  * caller never named one (a single-membership session resolves the company

package/dist/lib/billing/plan-limit-upgrade-url.d.ts

@@ -0,0 +1,13 @@
+export declare const PLAN_LIMIT_UPGRADE_FALLBACK_FLAG = "cli.plan-limit-upgrade-fallback";
+export declare const PLAN_LIMIT_UPGRADE_FALLBACK_DEFAULT = false;
+export interface PlanLimitUpgradeUrlChoices {
+    topLevelUrl?: string | null;
+    nestedUrl?: string | null;
+    legacyUrl: string;
+}
+export declare function isPlanLimitUpgradeFallbackEnabled(): boolean;
+/** Resolve a server URL without changing legacy behavior while the flag is off. */
+export declare function selectPlanLimitUpgradeUrl(companySlug: string | undefined, choices: PlanLimitUpgradeUrlChoices): string;
+/** Keep a caller's previous URL until the hq-flags rollout is enabled. */
+export declare function planLimitUpgradeFallbackUrl(companySlug: string | undefined, previousFallbackUrl: string): string;
+//# sourceMappingURL=plan-limit-upgrade-url.d.ts.map

package/dist/lib/billing/plan-limit-upgrade-url.js

@@ -0,0 +1,38 @@
+import { resolveProcessFlagGate } from "../flag-registry.js";
+import { DEFAULT_VAULT_API_URL } from "../../utils/cognito-session.js";
+import { consoleOrigin } from "../../utils/console-origin.js";
+export const PLAN_LIMIT_UPGRADE_FALLBACK_FLAG = "cli.plan-limit-upgrade-fallback";
+export const PLAN_LIMIT_UPGRADE_FALLBACK_DEFAULT = false;
+export function isPlanLimitUpgradeFallbackEnabled() {
+    return resolveProcessFlagGate(PLAN_LIMIT_UPGRADE_FALLBACK_FLAG, { fallback: PLAN_LIMIT_UPGRADE_FALLBACK_DEFAULT }, () => PLAN_LIMIT_UPGRADE_FALLBACK_DEFAULT);
+}
+function companyBillingUrl(companySlug) {
+    const controlPlaneUrl = process.env.HQ_VAULT_API_URL?.trim() || DEFAULT_VAULT_API_URL;
+    const origin = consoleOrigin(controlPlaneUrl);
+    if (!origin)
+        return null;
+    const slug = companySlug?.trim();
+    const route = slug
+        ? `/companies/${encodeURIComponent(slug)}/billing?upgrade=1`
+        : "/billing";
+    return `${origin}${route}`;
+}
+/** Resolve a server URL without changing legacy behavior while the flag is off. */
+export function selectPlanLimitUpgradeUrl(companySlug, choices) {
+    if (!isPlanLimitUpgradeFallbackEnabled())
+        return choices.legacyUrl;
+    const topLevelUrl = choices.topLevelUrl?.trim() || undefined;
+    const nestedUrl = choices.nestedUrl?.trim() || undefined;
+    const generatedUrl = companyBillingUrl(companySlug);
+    if (companySlug?.trim()) {
+        return generatedUrl ?? topLevelUrl ?? nestedUrl ?? choices.legacyUrl;
+    }
+    return topLevelUrl ?? nestedUrl ?? generatedUrl ?? choices.legacyUrl;
+}
+/** Keep a caller's previous URL until the hq-flags rollout is enabled. */
+export function planLimitUpgradeFallbackUrl(companySlug, previousFallbackUrl) {
+    return selectPlanLimitUpgradeUrl(companySlug, {
+        legacyUrl: previousFallbackUrl,
+    });
+}
+//# sourceMappingURL=plan-limit-upgrade-url.js.map

package/dist/lib/billing/plan-lock.d.ts

@@ -85,6 +85,7 @@ export declare function parseFreeMonth(value: unknown): PlanLimitFreeMonth | und
  */
 export declare function selectCompanyMembership(body: unknown, companyRef: string): {
     companyUid?: string;
+    companySlug?: string;
 } | null;
 /** Parse the resolved plan id out of a usage-limits body. Absent → null. */
 export declare function selectPlan(body: unknown): "free" | "paid" | "enterprise" | null;

package/dist/lib/billing/plan-lock.js

@@ -22,6 +22,7 @@
  */
 import chalk from "chalk";
 import { vaultApiFetch } from "../../utils/vault-api.js";
+import { selectPlanLimitUpgradeUrl } from "./plan-limit-upgrade-url.js";
 /**
  * Dimensions the bind notice names with a remedy. Owner decision 7 (2026-09-17)
  * fixes the nagging set at these four: `deployments` and `storageBytes` are
@@ -133,6 +134,7 @@ export function selectCompanyMembership(body, companyRef) {
             continue;
         return {
             companyUid: typeof row.companyUid === "string" ? row.companyUid : undefined,
+            companySlug: typeof row.companySlug === "string" ? row.companySlug : undefined,
         };
     }
     return null;
@@ -157,12 +159,20 @@ export function selectMemberUsage(body) {
         : STARTER_MEMBER_TARGET;
     return { used: users.used, limit };
 }
-function selectUpgradeUrl(body) {
+function selectUpgradeUrl(body, companySlug) {
     const rec = asRecord(body);
-    const raw = rec?.upgradeUrl;
-    if (typeof raw === "string" && raw.trim().length > 0)
-        return raw.trim();
-    return DEFAULT_UPGRADE_URL;
+    const nested = asRecord(rec?.planLimits);
+    const topLevelUrl = typeof rec?.upgradeUrl === "string" && rec.upgradeUrl.trim().length > 0
+        ? rec.upgradeUrl.trim()
+        : undefined;
+    const nestedUrl = typeof nested?.upgradeUrl === "string" && nested.upgradeUrl.trim().length > 0
+        ? nested.upgradeUrl.trim()
+        : undefined;
+    return selectPlanLimitUpgradeUrl(companySlug, {
+        topLevelUrl,
+        nestedUrl,
+        legacyUrl: topLevelUrl ?? DEFAULT_UPGRADE_URL,
+    });
 }
 /**
  * Read over-limit dimensions from a usage-limits body. `planLimits` nested
@@ -195,7 +205,7 @@ export function selectUsages(body) {
     }
     return out;
 }
-function statusFromUsage(companySlug, companyUid, body) {
+function statusFromUsage(companySlug, companyUid, body, upgradeCompanySlug) {
     const usages = selectUsages(body);
     const reasons = selectOverReasons(body);
     const rec = asRecord(body);
@@ -207,7 +217,7 @@ function statusFromUsage(companySlug, companyUid, body) {
         reasons,
         members: selectMemberUsage(body) ?? usages.users,
         usages,
-        upgradeUrl: selectUpgradeUrl(body),
+        upgradeUrl: selectUpgradeUrl(body, upgradeCompanySlug),
         freeMonth: parseFreeMonth(rec?.freeMonth),
         plan: selectPlan(body) ?? undefined,
         checkedAt: new Date().toISOString(),
@@ -242,7 +252,9 @@ export async function fetchPlanLimitStatus(token, companyRef, opts = {}) {
         const body = await usage.json().catch(() => null);
         if (!body)
             return null;
-        return statusFromUsage(companyRef, selected.companyUid, body);
+        const selectedSlug = selected.companySlug ??
+            (!companyRef.startsWith("cmp_") ? companyRef : undefined);
+        return statusFromUsage(companyRef, selected.companyUid, body, selectedSlug);
     }
     catch {
         return null;

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

@@ -36,6 +36,8 @@ import chalk from "chalk";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { resolveProcessFlagCompanyContext } from "./flag-registry.js";
+import { isPlanLimitUpgradeFallbackEnabled, planLimitUpgradeFallbackUrl, selectPlanLimitUpgradeUrl, } from "./billing/plan-limit-upgrade-url.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
@@ -155,6 +157,18 @@ function parsePlanLimits(body) {
         }
         : null;
 }
+function parseNestedUpgradeUrl(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return null;
+    }
+    const planLimits = body.planLimits;
+    if (planLimits === null ||
+        typeof planLimits !== "object" ||
+        Array.isArray(planLimits)) {
+        return null;
+    }
+    return parseUpgradeUrl(planLimits.upgradeUrl);
+}
 /**
  * Defensively parse the top-level `thresholdCrossings` array.
  *
@@ -208,14 +222,31 @@ function parseThresholdCrossings(body) {
 export function recordPlanLimitStatus(body, opts = {}) {
     try {
         const status = parsePlanLimits(body);
+        const crossings = parseThresholdCrossings(body);
+        let resolvedUpgradeUrl = null;
+        if (status !== null || crossings.length > 0) {
+            const bodyRecord = body !== null && typeof body === "object" && !Array.isArray(body)
+                ? body
+                : null;
+            const topLevelUpgradeUrl = parseUpgradeUrl(bodyRecord?.upgradeUrl);
+            const nestedUpgradeUrl = parseNestedUpgradeUrl(body);
+            const companySlug = isPlanLimitUpgradeFallbackEnabled()
+                ? resolveProcessFlagCompanyContext().companySlug
+                : undefined;
+            resolvedUpgradeUrl = selectPlanLimitUpgradeUrl(companySlug, {
+                topLevelUrl: topLevelUpgradeUrl,
+                nestedUrl: nestedUpgradeUrl,
+                legacyUrl: status?.upgradeUrl ?? PLAN_LIMIT_UPGRADE_URL,
+            });
+        }
         if (status !== null) {
             const anyOver = Object.values(status.limits).some((e) => e.over);
-            lastSeen = { ...status, anyOver };
+            lastSeen = { ...status, anyOver, upgradeUrl: resolvedUpgradeUrl };
         }
         // Independent of `planLimits`: the server can announce a crossing on a
         // response whose nag map this CLI could not parse, and the notice is the
         // one surface that must land inside a session that is already running.
-        emitPlanLimitThresholdNotice(parseThresholdCrossings(body), status?.upgradeUrl ?? null, opts);
+        emitPlanLimitThresholdNotice(crossings, resolvedUpgradeUrl, opts);
     }
     catch {
         // Never throw from record path.
@@ -402,7 +433,8 @@ export function emitPlanLimitThresholdNotice(crossings, upgradeUrl, opts = {}) {
         const write = opts.write ?? ((s) => process.stderr.write(s));
         const statePath = opts.statePath ?? defaultStatePath();
         const stored = readNagState(statePath).notifiedThresholds ?? {};
-        const resolvedUpgradeUrl = upgradeUrl ?? PLAN_LIMIT_UPGRADE_URL;
+        const resolvedUpgradeUrl = upgradeUrl ??
+            planLimitUpgradeFallbackUrl(resolveProcessFlagCompanyContext().companySlug, PLAN_LIMIT_UPGRADE_URL);
         const printed = {};
         for (const crossing of crossings) {
             const key = crossingKey(crossing);
@@ -440,7 +472,8 @@ export function emitPlanLimitNag(opts = {}) {
         const now = opts.now ?? (() => new Date());
         const statePath = opts.statePath ?? defaultStatePath();
         const { limits, anyOver, upgradeUrl } = lastSeen;
-        const resolvedUpgradeUrl = upgradeUrl ?? PLAN_LIMIT_UPGRADE_URL;
+        const resolvedUpgradeUrl = upgradeUrl ??
+            planLimitUpgradeFallbackUrl(resolveProcessFlagCompanyContext().companySlug, PLAN_LIMIT_UPGRADE_URL);
         const entries = Object.entries(limits);
         if (entries.length === 0)
             return;

package/dist/lib/test-utils/isolated-flag-company-context.d.ts

@@ -0,0 +1,3 @@
+/** Keep process-wide flag tests independent of the developer machine binding. */
+export declare function isolateFlagCompanyContext(): () => void;
+//# sourceMappingURL=isolated-flag-company-context.d.ts.map

package/dist/lib/test-utils/isolated-flag-company-context.js

@@ -0,0 +1,18 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { vi } from "vitest";
+/** Keep process-wide flag tests independent of the developer machine binding. */
+export function isolateFlagCompanyContext() {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "hq-flag-company-context-"));
+    vi.stubEnv("HOME", home);
+    vi.stubEnv("HQ_COMPANY_UID", undefined);
+    vi.stubEnv("HQ_COMPANY_SLUG", undefined);
+    vi.stubEnv("HQ_SPAWN_COMPANY", undefined);
+    vi.stubEnv("HQ_SESSION_ID", undefined);
+    vi.stubEnv("HQ_AGENT_IDENTITY_FILE", "");
+    vi.stubEnv("HQ_ROOT", undefined);
+    vi.stubEnv("HQ_WORK_CONTEXT_ROOT", undefined);
+    return () => fs.rmSync(home, { recursive: true, force: true });
+}
+//# sourceMappingURL=isolated-flag-company-context.js.map

package/dist/utils/console-origin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The console that fronts the control plane this CLI is pointed at.
+ *
+ * A handoff must land on the console for the same backend. When an override is
+ * active, derive its console from the control-plane host instead of assuming
+ * production. `HQ_CONSOLE_URL` remains an explicit override.
+ */
+export declare function consoleOrigin(vaultApiUrl?: string): string | undefined;
+//# sourceMappingURL=console-origin.d.ts.map

package/dist/utils/console-origin.js

@@ -0,0 +1,28 @@
+import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
+const PRODUCTION_CONSOLE_ORIGIN = "https://hq.computer";
+const PRODUCTION_VAULT_API_HOST = "hqapi.hq.computer";
+/**
+ * The console that fronts the control plane this CLI is pointed at.
+ *
+ * A handoff must land on the console for the same backend. When an override is
+ * active, derive its console from the control-plane host instead of assuming
+ * production. `HQ_CONSOLE_URL` remains an explicit override.
+ */
+export function consoleOrigin(vaultApiUrl = DEFAULT_VAULT_API_URL) {
+    const explicit = process.env.HQ_CONSOLE_URL?.trim();
+    if (explicit)
+        return explicit.replace(/\/+$/, "");
+    let api;
+    try {
+        api = new URL(vaultApiUrl);
+    }
+    catch {
+        return undefined;
+    }
+    if (api.host === PRODUCTION_VAULT_API_HOST)
+        return PRODUCTION_CONSOLE_ORIGIN;
+    if (!api.hostname.startsWith("hqapi."))
+        return undefined;
+    return `${api.protocol}//${api.host.slice("hqapi.".length)}`;
+}
+//# sourceMappingURL=console-origin.js.map

package/package.json

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