@indigoai-us/hq-cli 5.345.159 → 5.345.160

package/dist/lib/hook-engine/resolve.d.ts

@@ -1,3 +1,4 @@
+import { type SpawnSyncReturns } from 'node:child_process';
 export declare const HOOK_ENGINE_REPAIR = "npm install -g @indigoai-us/hq-cli --include=optional";
 export declare const HOOK_ENGINE_REPAIR_PIN = "hq core hook-engine-path --repair";
 export interface EngineOptions {
@@ -23,6 +24,19 @@ export declare function pinnedHookEngineMatches(engine: EnginePackage): boolean;
 export declare function findHookEngine(options?: EngineOptions): EnginePackage | null;
 /** Never truncate or replace a running Windows executable. */
 export declare function installHookEngine(options?: EngineOptions): string | null;
+/** master-hook.sh reads this one-line file with shell builtins to find the
+ * pinned engine without starting Node (US-021 bridge). It always names the
+ * engine of the CLI that wrote it, so a CLI update retargets it. */
+export declare function hookEnginePointerPath(options?: EngineOptions): string;
+/** Best effort and atomic: a missing pointer only keeps the bridge off. */
+export declare function writeHookEnginePointer(pinned: string, options?: EngineOptions): void;
+export declare function removeHookEnginePointer(options?: EngineOptions): void;
+export interface VerifyOptions {
+    spawn?: (command: string, args: readonly string[]) => Pick<SpawnSyncReturns<string>, 'status' | 'stdout' | 'error'>;
+}
+/** Run the engine's own `--self-check` and read its report. Returns the
+ * problem as text, or null when the binary answers as an hq-hook engine. */
+export declare function verifyHookEngine(binary: string, options?: VerifyOptions): string | null;
 /** Call only after settings no longer reference these old versions. Windows
  * refuses unlink of a mapped executable; a busy version stays for a later pass.
  * POSIX permits unlink while running, so retain those versions conservatively.

package/dist/lib/hook-engine/resolve.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
-import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, unlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 const require = createRequire(import.meta.url);
@@ -104,8 +105,61 @@ export function installHookEngine(options = {}) {
     if (!pinnedHookEngineMatches(engine)) {
         throw new Error(`Hook engine ${engine.version} differs from its pinned copy; close HQ sessions and repair with: ${HOOK_ENGINE_REPAIR_PIN}`);
     }
+    writeHookEnginePointer(engine.pinned, options);
     return engine.pinned;
 }
+/** master-hook.sh reads this one-line file with shell builtins to find the
+ * pinned engine without starting Node (US-021 bridge). It always names the
+ * engine of the CLI that wrote it, so a CLI update retargets it. */
+export function hookEnginePointerPath(options = {}) {
+    return join(options.home ?? homedir(), '.hq', 'bin', 'hq-hook', 'current');
+}
+/** Best effort and atomic: a missing pointer only keeps the bridge off. */
+export function writeHookEnginePointer(pinned, options = {}) {
+    const pointer = hookEnginePointerPath(options);
+    try {
+        mkdirSync(dirname(pointer), { recursive: true });
+        const stage = `${pointer}.${process.pid}.tmp`;
+        writeFileSync(stage, `${pinned}\n`);
+        renameSync(stage, pointer);
+    }
+    catch {
+        // The hook path falls back to bash when the pointer is absent.
+    }
+}
+export function removeHookEnginePointer(options = {}) {
+    try {
+        unlinkSync(hookEnginePointerPath(options));
+    }
+    catch { /* already absent */ }
+}
+/** Run the engine's own `--self-check` and read its report. Returns the
+ * problem as text, or null when the binary answers as an hq-hook engine. */
+export function verifyHookEngine(binary, options = {}) {
+    const spawn = options.spawn ?? ((command, args) => spawnSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000 }));
+    let result;
+    try {
+        result = spawn(binary, ['--self-check']);
+    }
+    catch (error) {
+        return `hook engine self-check could not start: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    if (result.error)
+        return `hook engine self-check could not start: ${result.error.message}`;
+    let report;
+    try {
+        report = JSON.parse(String(result.stdout ?? '').trim().split('\n').pop() ?? '');
+    }
+    catch {
+        return `hook engine self-check printed no report (exit ${result.status ?? 'signal'})`;
+    }
+    if (report.engine !== 'hq-hook' || typeof report.version !== 'string' || typeof report.bridge_schema !== 'number') {
+        return 'hook engine self-check report is not from hq-hook';
+    }
+    if (result.status !== 0 || report.ok !== true)
+        return `hook engine self-check failed: ${typeof report.error === 'string' ? report.error : `exit ${result.status ?? 'signal'}`}`;
+    return null;
+}
 /** Call only after settings no longer reference these old versions. Windows
  * refuses unlink of a mapped executable; a busy version stays for a later pass.
  * POSIX permits unlink while running, so retain those versions conservatively.

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

@@ -79,22 +79,6 @@ export declare function recordPlanLimitStatus(body: unknown, opts?: {
  * never claims the workspace has stopped working.
  */
 export declare function buildOverLine(overEntries: Array<[string, PlanLimitEntry]>, upgradeUrl: string): string;
-/**
- * My Telemetry is an Individual-plan feature on a personal scope (owner
- * decision 9 / us-044-individual-plan-design.md §11). When hq-pro refuses it,
- * the CLI prints this notice INSTEAD of telemetry output.
- *
- * It lives beside the nag copy so plan wording stays in one file, but it is
- * NOT part of the nag model: no persistence, no throttle, no episode state. It
- * is rendered once, on the spot, by whoever received the refusal. The refusal
- * is a plan fact, so it neither counts toward the nag bands nor is silenced by
- * the nag cadence.
- *
- * Copy names the plan and its price only — no Outposts, no bot pricing (owner
- * decisions 10 and 11).
- */
-export declare const INDIVIDUAL_PLAN_NAME = "Individual";
-export declare const INDIVIDUAL_PRICE_LABEL = "$50/mo";
 /**
  * The notice a personal feature refusal prints. `upgradeUrl` is the server's
  * own checkout target; an older hq-pro sends none, and the line then names the

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

@@ -367,16 +367,18 @@ export function buildOverLine(overEntries, upgradeUrl) {
     const facts = overEntries
         .map(([key, entry]) => `${PLAN_LIMIT_DIMENSION_LABELS[key] ?? key} ${entry.used} of ${entry.limit}`)
         .join(", ");
-    return (`⚠ HQ Starter: ${facts}. New files and new secrets are paused. ` +
-        `Upgrade: ${upgradeUrl}`);
+    // US-024: names no plan and offers no upgrade; the link is the Billing page.
+    return (`⚠ Over this account's limits: ${facts}. New files and new secrets are paused. ` +
+        `Billing: ${upgradeUrl}`);
 }
 // ---------------------------------------------------------------------------
-// Individual-plan feature notice (US-054)
+// Personal feature notice (US-054, copy per US-024)
 // ---------------------------------------------------------------------------
 /**
- * My Telemetry is an Individual-plan feature on a personal scope (owner
- * decision 9 / us-044-individual-plan-design.md §11). When hq-pro refuses it,
- * the CLI prints this notice INSTEAD of telemetry output.
+ * My Telemetry is a paid feature on a personal scope (owner decision 9 /
+ * us-044-individual-plan-design.md §11). When hq-pro refuses it, the CLI
+ * prints this notice INSTEAD of telemetry output. The flat personal plan is
+ * closed (US-024), so the notice names no plan or price.
  *
  * It lives beside the nag copy so plan wording stays in one file, but it is
  * NOT part of the nag model: no persistence, no throttle, no episode state. It
@@ -384,11 +386,8 @@ export function buildOverLine(overEntries, upgradeUrl) {
  * is a plan fact, so it neither counts toward the nag bands nor is silenced by
  * the nag cadence.
  *
- * Copy names the plan and its price only — no Outposts, no bot pricing (owner
- * decisions 10 and 11).
+ * No Outposts and no bot pricing in the copy (owner decisions 10 and 11).
  */
-export const INDIVIDUAL_PLAN_NAME = "Individual";
-export const INDIVIDUAL_PRICE_LABEL = "$50/mo";
 /** Human names for the features a personal scope can be refused. */
 const PERSONAL_FEATURE_LABELS = {
     telemetry: "My Telemetry",
@@ -403,11 +402,11 @@ export function renderPersonalPlanFeatureNotice(feature, upgradeUrl, opts = {})
     // 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 headline = `${label} is not included on your personal account's current billing.`;
     const action = typeof upgradeUrl === "string" && upgradeUrl.trim().length > 0
-        ? `Upgrade: ${upgradeUrl.trim()}`
-        : "Upgrade in your HQ billing settings.";
-    return `${headline} Your personal account is on the free tier. ${action}`;
+        ? `Billing: ${upgradeUrl.trim()}`
+        : "See your HQ billing settings.";
+    return `${headline} ${action}`;
 }
 /** `"{resource}:{band}"` — the persisted key, matching the server's own. */
 function crossingKey(crossing) {
@@ -429,9 +428,9 @@ export function renderThresholdNotice(crossing, upgradeUrl) {
     const name = dimensionName(crossing.resource);
     const counts = `${crossing.used} of ${crossing.limit}`;
     const headline = crossing.band === "over"
-        ? `HQ Starter: you are past your ${name} limit (${counts}).`
-        : `HQ Starter: you have reached 80% of your ${name} (${counts}).`;
-    return `${headline} Upgrade: ${upgradeUrl}`;
+        ? `You are past your ${name} limit (${counts}).`
+        : `You have reached 80% of your ${name} limit (${counts}).`;
+    return `${headline} Billing: ${upgradeUrl}`;
 }
 /**
  * Print every crossing this machine has not already printed for this episode.
@@ -521,7 +520,7 @@ export function emitPlanLimitNag(opts = {}) {
         if (worst === null)
             return;
         warningShownThisSession = true;
-        const line = `⚠ HQ Starter: ${formatEntryLine(worst.key, worst.entry)}. Add headroom before you hit the cap: ${resolvedUpgradeUrl}`;
+        const line = `⚠ Nearing this account's limits: ${formatEntryLine(worst.key, worst.entry)}. Make room before you hit the cap. Billing: ${resolvedUpgradeUrl}`;
         write(chalk.yellow(line) + "\n");
         if (isCliLimitResourceKind(worst.key)) {
             queueCliLimitNoticeExposure(worst.key, "advisory");

package/dist/main.d.ts

@@ -9,7 +9,6 @@ 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
  * the hard version decision, pre-action observability, and release-health
@@ -44,7 +43,6 @@ export type TopLevelErrorDependencies = {
     argv?: readonly string[];
     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.

package/dist/main.js

@@ -40,9 +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, withPricingPlan, } from "./utils/plan-gate-error.js";
+import { canOfferTeamUpgrade, formatPlanGateError, offerUpgradeLink, planGateActionUrl, 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";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
@@ -654,8 +653,8 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
     }
     else if (planGate) {
         // Plan denials are expected product limits, never a CLI crash. The
-        // server URL is always shown. Company refusals that the Workforce
-        // checkout satisfies retain the direct Stripe checkout action.
+        // server URL is always shown. The flat-plan checkout is closed, so the
+        // only offer is to open the server's billing link.
         //
         // A plan-limit refusal (a Starter hard stop) always prints its reason,
         // usage and fix options, even non-interactively: the user can fix it
@@ -671,60 +670,23 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             ? queueCliLimitNoticeExposure(planGate.details.resource, "refusal", planGate.details.companyUid)
             : null;
         deps.setExitCode(1);
-        // 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) &&
-                (planGate.code === "PLAN_REQUIRED" ||
-                    planGate.code === "MEETING_PLAN_REQUIRED" ||
-                    planGate.code === "BILLING_REQUIRED");
-            if (isCompanyWorkforceCheckout && companyUid) {
-                try {
-                    const upgraded = await offerTeamUpgrade(async () => {
-                        await (deps.upgradeToTeam ?? upgradeToTeam)({ companyUid });
-                    }, {
-                        interactive: true,
-                        argv: deps.argv,
-                        ask: deps.ask,
-                    });
-                    if (upgraded)
-                        queueCliLimitNoticeEngagement(promptExposure);
-                }
-                catch (upgradeErr) {
-                    const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
-                    deps.stderr.write(`hq: ${message}\n`);
-                    try {
-                        const opened = await offerUpgradeLink(planGate.details.upgradeUrl, {
-                            interactive: true,
-                            argv: deps.argv,
-                            ask: deps.ask,
-                            openUrl: deps.openUrl,
-                        });
-                        if (opened)
-                            queueCliLimitNoticeEngagement(promptExposure);
-                    }
-                    catch (linkErr) {
-                        const linkMessage = linkErr instanceof Error ? linkErr.message : String(linkErr);
-                        deps.stderr.write(`hq: ${linkMessage}\n`);
-                    }
-                }
+        // A usage-only account has no plan to buy: no upgrade offer. A usage
+        // pause offers its own Billing link.
+        const actionUrl = planGateActionUrl(planGate);
+        if (interactive && actionUrl && (!usageOnlyGate || planGate.details.usagePause)) {
+            try {
+                const opened = await offerUpgradeLink(actionUrl, {
+                    interactive: true,
+                    argv: deps.argv,
+                    ask: deps.ask,
+                    openUrl: deps.openUrl,
+                });
+                if (opened)
+                    queueCliLimitNoticeEngagement(promptExposure);
             }
-            else {
-                try {
-                    const opened = await offerUpgradeLink(planGate.details.upgradeUrl, {
-                        interactive: true,
-                        argv: deps.argv,
-                        ask: deps.ask,
-                        openUrl: deps.openUrl,
-                    });
-                    if (opened)
-                        queueCliLimitNoticeEngagement(promptExposure);
-                }
-                catch (upgradeErr) {
-                    const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
-                    deps.stderr.write(`hq: ${message}\n`);
-                }
+            catch (upgradeErr) {
+                const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
+                deps.stderr.write(`hq: ${message}\n`);
             }
         }
     }

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

@@ -1,7 +1,7 @@
 import { type PlanLimitFreeMonth } from "../lib/billing/free-month.js";
-import { type PricingPlan } from "../lib/billing/usage-only.js";
+import { type PricingPlan, type UsagePause } 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. */
+/** A PERSONAL scope asked for a feature its current plan does not include. */
  | "PERSONAL_PLAN_REQUIRED"
 /** External agent enrollment was denied by the company plan. */
  | "BILLING_REQUIRED";
@@ -29,19 +29,41 @@ export interface PlanGateDetails {
     /** 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.
+     * Usage pricing (US-012): from the 402 body (`billingState` first, then the
+     * legacy `pricingPlan`), or attached by the caller from the membership row,
+     * usage-limits or the billing summary. `"usage-only"` renders no retired
+     * plan copy and no plan upgrade link. Absent (unknown) renders neutral copy
+     * that names no plan.
      */
     pricingPlan?: PricingPlan;
+    /**
+     * The server's usage pause (`usagePause` on the 402 body, hq-pro
+     * src/billing/usage-pause.ts). When present its message is the whole
+     * refusal and its `actionUrl` the only link.
+     */
+    usagePause?: UsagePause;
+    /**
+     * Hard-stop 402: true when HQ Workforce is closed to the company (hq-pro
+     * `billing.legacy-plans-closed`, owner decision 2026-10-19). `upgradeUrl`
+     * is then the usage-pricing switch page; the refusal offers the switch and
+     * never the free Workforce month.
+     */
+    legacyPlansClosed?: boolean;
 }
 /** 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. */
+/**
+ * One renderer for server-selected billing links across CLI refusals. The
+ * link is labelled `Billing:`, or `Switch:` when the server said it is the
+ * usage-pricing switch page. It never says "Upgrade": the flat plans that
+ * word led to are closed.
+ */
 export declare function formatUpgradeRefusal(reason: string, upgradeUrl: string | undefined, options?: {
     urlOnly?: boolean;
+    legacyPlansClosed?: boolean;
 }): string;
+/** The link a refusal offers: the usage pause's action, else the server's upgrade URL. */
+export declare function planGateActionUrl(err: PlanGateError): string | undefined;
 /** Recover a company UID only from the server's UID-keyed billing callback. */
 export declare function companyUidFromPlanUpgradeUrl(value: unknown): string | undefined;
 export declare class PlanGateError extends Error {
@@ -61,14 +83,8 @@ export interface UpgradeLinkOfferDependencies {
     argv?: readonly string[];
     interactive?: boolean;
 }
-/** Ask before opening the exact URL returned by the server. */
+/** Ask before opening the exact billing URL returned by the server. */
 export declare function offerUpgradeLink(url: string, deps?: UpgradeLinkOfferDependencies): Promise<boolean>;
-/** Legacy checkout callback retained for callers outside the shared refusal paths. */
-export declare function offerTeamUpgrade(onConfirm: () => Promise<void>, deps?: {
-    ask?: (question: string) => Promise<string>;
-    argv?: readonly string[];
-    interactive?: boolean;
-}): Promise<boolean>;
 /** Decode an already-read JSON envelope from either shared HTTP client. */
 export declare function planGateErrorFromPayload(status: number, body: unknown, companyUid?: string): PlanGateError | null;
 /**

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

@@ -6,9 +6,9 @@
 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;
+import { isUsageOnly, pricingPlanFromBody, usageOnlyCardRequiredLines, usagePauseFromBody, USAGE_PRICING_POINTER, } from "../lib/billing/usage-only.js";
+/** Retired plan names, prices and offers a usage-only account must never be shown. */
+const LEGACY_PLAN_COPY = /Starter|Workforce|Individual|\$500|\$50\b|free month|upgrade|plan limit/i;
 /** Copy a plan gate with the caller's pricing plan attached. */
 export function withPricingPlan(err, pricingPlan) {
     if (!pricingPlan || err.details.pricingPlan === pricingPlan)
@@ -100,23 +100,28 @@ function planLimitRefusalText(head, details) {
             `${formatResourceAmount(row.resource, row.used)} of ` +
             `${formatResourceAmount(row.resource, row.limit)} used.`);
     }
+    // The free month led to the flat-plan checkout, which is closed; it is
+    // never offered. The way out besides trimming is the switch to usage
+    // pricing, offered only when the server said the company is on an earlier
+    // plan (or that the flat plans are closed to it).
     const fixes = [];
-    const freeMonthUrl = safeUpgradeUrl(details.freeMonth?.url);
-    if (details.freeMonth?.eligible && freeMonthUrl) {
-        fixes.push(`Start your free month — add a card, first month free: ${freeMonthUrl}`);
-    }
     for (const [resource, target] of Object.entries(details.fixOptions ?? {})) {
-        fixes.push(`${resourceFixAction(resource)} to make room (your plan allows ` +
+        fixes.push(`${resourceFixAction(resource)} to make room (the limit is ` +
             `${formatResourceAmount(resource, target)}).`);
     }
     if (fixes.length > 0) {
-        fixes.push("Upgrade your plan.");
+        fixes.push(details.legacyPlansClosed || details.pricingPlan === "current"
+            ? "Switch to usage pricing: no plan fee, and these limits stop applying."
+            : "Open the company's Billing page.");
         lines.push("  Ways to sort it:");
         fixes.forEach((fix, index) => lines.push(`    ${index + 1}. ${fix}`));
     }
     return lines.join("\n");
 }
 function planGateReason(code, details) {
+    // The server's usage pause is the whole answer: its message, nothing added.
+    if (details.usagePause)
+        return details.usagePause.message;
     if (isUsageOnly(details.pricingPlan))
         return usageOnlyPlanGateReason(code, details);
     if (code === "PLAN_LIMIT_EXCEEDED") {
@@ -125,9 +130,9 @@ function planGateReason(code, details) {
             : typeof details.resource === "string" &&
                 typeof details.used === "number" &&
                 typeof details.limit === "number"
-                ? `Starter plan limit reached: ${details.resource} ${details.used}/${details.limit} used.`
+                ? `Limit reached: ${details.resource} ${details.used}/${details.limit} used.`
                 : details.resources?.length || details.fixOptions || details.freeMonth
-                    ? "Your plan limit has been reached."
+                    ? "This account has reached a limit."
                     : undefined;
         if (head)
             return planLimitRefusalText(head, details);
@@ -138,14 +143,19 @@ function planGateReason(code, details) {
         return renderPersonalPlanFeatureNotice(details.feature ?? "this feature", null);
     }
     if (code === "MEETING_PLAN_REQUIRED") {
-        return "HQ Workforce plan required to invite a meeting bot.";
+        return "Meeting notetaker bots are not available on this company's current billing.";
     }
     if (code === "BILLING_REQUIRED") {
-        return "Upgrade the company plan before enrolling an external agent.";
+        return "Set up billing for this company before enrolling an external agent.";
     }
-    return "HQ Workforce plan required for this feature.";
+    return "This feature is not available on this company's current billing.";
 }
-/** One renderer for server-selected upgrade links across CLI plan refusals. */
+/**
+ * One renderer for server-selected billing links across CLI refusals. The
+ * link is labelled `Billing:`, or `Switch:` when the server said it is the
+ * usage-pricing switch page. It never says "Upgrade": the flat plans that
+ * word led to are closed.
+ */
 export function formatUpgradeRefusal(reason, upgradeUrl, options = {}) {
     const safeUrl = safeUpgradeUrl(upgradeUrl);
     const cliLimitUrl = safeUrl ? withCliLimitEntrySurface(safeUrl) : undefined;
@@ -153,7 +163,11 @@ export function formatUpgradeRefusal(reason, upgradeUrl, options = {}) {
         return cliLimitUrl;
     if (!cliLimitUrl)
         return reason;
-    return `${reason}\nUpgrade: ${cliLimitUrl}`;
+    return `${reason}\n${options.legacyPlansClosed ? "Switch" : "Billing"}: ${cliLimitUrl}`;
+}
+/** The link a refusal offers: the usage pause's action, else the server's upgrade URL. */
+export function planGateActionUrl(err) {
+    return err.details.usagePause?.actionUrl ?? err.details.upgradeUrl;
 }
 function safeUpgradeUrl(value) {
     if (typeof value !== "string" ||
@@ -187,6 +201,9 @@ export function companyUidFromPlanUpgradeUrl(value) {
     return match?.[1];
 }
 function formatPlanGateErrorText(code, details) {
+    if (details.usagePause) {
+        return formatUpgradeRefusal(details.usagePause.message, details.usagePause.actionUrl);
+    }
     if (isUsageOnly(details.pricingPlan))
         return planGateReason(code, details);
     return formatUpgradeRefusal(planGateReason(code, details), details.upgradeUrl);
@@ -206,17 +223,21 @@ export function isPlanGateError(err) {
 }
 /** Plain, stable CLI copy for plan-gated resource creation. */
 export function formatPlanGateError(err, options = {}) {
+    // A usage pause: the server's message and its Billing link, nothing else.
+    if (err.details.usagePause) {
+        return formatUpgradeRefusal(err.details.usagePause.message, err.details.usagePause.actionUrl, { urlOnly: options.urlOnly });
+    }
     // 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);
+    return formatUpgradeRefusal(planGateReason(err.code, err.details), err.details.upgradeUrl, { ...options, legacyPlansClosed: err.details.legacyPlansClosed === true });
 }
 export function canOfferTeamUpgrade(argv = process.argv) {
     return Boolean(process.stdin.isTTY && process.stderr.isTTY) &&
         !process.env.CI &&
         !argv.includes("--json");
 }
-/** Ask before opening the exact URL returned by the server. */
+/** Ask before opening the exact billing URL returned by the server. */
 export async function offerUpgradeLink(url, deps = {}) {
     const safeUrl = safeUpgradeUrl(url);
     if (!safeUrl)
@@ -226,13 +247,13 @@ export async function offerUpgradeLink(url, deps = {}) {
         return false;
     let answer;
     if (deps.ask) {
-        answer = await deps.ask("Open upgrade link now? [y/N] ");
+        answer = await deps.ask("Open the billing link now? [y/N] ");
     }
     else {
         const { createInterface } = await import("node:readline/promises");
         const readline = createInterface({ input: process.stdin, output: process.stderr });
         try {
-            answer = await readline.question("Open upgrade link now? [y/N] ");
+            answer = await readline.question("Open the billing link now? [y/N] ");
         }
         finally {
             readline.close();
@@ -249,38 +270,29 @@ export async function offerUpgradeLink(url, deps = {}) {
     }
     return true;
 }
-/** Legacy checkout callback retained for callers outside the shared refusal paths. */
-export async function offerTeamUpgrade(onConfirm, deps = {}) {
-    if (!(deps.interactive ?? canOfferTeamUpgrade(deps.argv)))
-        return false;
-    if (deps.ask) {
-        const answer = await deps.ask("Upgrade now? (opens checkout) [y/N] ");
-        if (!/^y(?:es)?$/i.test(answer.trim()))
-            return false;
-        await onConfirm();
-        return true;
-    }
-    const { createInterface } = await import("node:readline/promises");
-    const readline = createInterface({ input: process.stdin, output: process.stderr });
-    try {
-        const answer = await readline.question("Upgrade now? (opens checkout) [y/N] ");
-        if (!/^y(?:es)?$/i.test(answer.trim()))
-            return false;
-        await onConfirm();
-        return true;
-    }
-    finally {
-        readline.close();
-    }
-}
 /** Decode an already-read JSON envelope from either shared HTTP client. */
 export function planGateErrorFromPayload(status, body, companyUid) {
     if (status !== 402 || !body || typeof body !== "object")
         return null;
     const payload = body;
-    const decoded = decodePlanGatePayload(payload, companyUid);
+    const usagePause = usagePauseFromBody(payload);
+    // A usage pause in a body this decoder does not otherwise know is still a
+    // refusal: the server's message is the whole answer.
+    const decoded = decodePlanGatePayload(payload, companyUid) ??
+        (usagePause
+            ? new PlanGateError("PLAN_LIMIT_EXCEEDED", {
+                reason: usagePause.message,
+                ...(usagePause.actionUrl ? { upgradeUrl: usagePause.actionUrl } : {}),
+                ...(companyUid ? { companyUid } : {}),
+            })
+            : null);
+    if (!decoded)
+        return null;
     const pricingPlan = pricingPlanFromBody(payload);
-    return decoded && pricingPlan ? withPricingPlan(decoded, pricingPlan) : decoded;
+    const withPlan = pricingPlan ? withPricingPlan(decoded, pricingPlan) : decoded;
+    return usagePause
+        ? new PlanGateError(withPlan.code, { ...withPlan.details, usagePause })
+        : withPlan;
 }
 function decodePlanGatePayload(payload, companyUid) {
     // US-054: the personal feature denial. hq-pro identifies it with
@@ -392,6 +404,7 @@ function planLimitRefusalFromPayload(payload, upgradeUrl, companyUid) {
             : undefined;
     const resources = parseResources(payload.resources);
     const fixOptions = parseFixOptions(payload.fixOptions);
+    const legacyPlansClosed = payload.legacyPlansClosed === true;
     const parsedFreeMonth = parseFreeMonth(payload.freeMonth);
     const freeMonthUrl = safeUpgradeUrl(parsedFreeMonth?.url);
     const freeMonth = parsedFreeMonth
@@ -416,6 +429,7 @@ function planLimitRefusalFromPayload(payload, upgradeUrl, companyUid) {
         ...(upgradeUrl ? { upgradeUrl } : {}),
         ...(reason ? { reason } : {}),
         ...(companyUid ? { companyUid } : {}),
+        ...(legacyPlansClosed ? { legacyPlansClosed } : {}),
     });
 }
 /** Wire codes that mark a vault/sync error as a plan-limit refusal. */

package/dist/utils/team-upgrade.d.ts

@@ -1,6 +1,15 @@
-export interface TeamUpgradeOptions {
-    company?: string;
-    companyUid?: string;
+/**
+ * `hq billing upgrade` for a company not on usage pricing (US-024).
+ *
+ * The flat plans are closed to new subscribers (hq-pro
+ * `billing.legacy-plans-closed`, owner decision 2026-10-19), so there is no
+ * checkout to open. The command points at the console's switch to usage
+ * pricing for the company. It POSTs nothing: the switch itself, and its owner
+ * gate, live on that page.
+ */
+export interface UsageSwitchOptions {
+    /** The company slug, for the company's switch page. */
+    companySlug?: string;
     noBrowser?: boolean;
     /** Testable override for environments where browser availability is known. */
     headless?: boolean;
@@ -9,9 +18,13 @@ export interface TeamUpgradeOptions {
     write?: (text: string) => void;
     error?: (text: string) => void;
 }
+/** The lines printed before the switch page link. Names no plan. */
+export declare function usageSwitchLines(url: string): string[];
+/** The fallback sentence when no console origin can be derived. */
+export declare const USAGE_SWITCH_NO_URL_MESSAGE = "Switch this company to usage pricing from its Billing page in the HQ Console.";
 /**
- * Start the owner-gated HQ Workforce Checkout flow. Stripe collects payment details
- * in its hosted browser page; the CLI never receives card data.
+ * Print (and open, unless told not to) the company's usage-pricing switch
+ * page. Returns the URL, or null when none could be built.
  */
-export declare function upgradeToTeam(opts?: TeamUpgradeOptions): Promise<string>;
+export declare function openUsageSwitch(opts?: UsageSwitchOptions): Promise<string | null>;
 //# sourceMappingURL=team-upgrade.d.ts.map