@indigoai-us/hq-cli 5.345.159 → 5.345.161

package/dist/lib/lanes/store.js

@@ -183,7 +183,7 @@ function sameFile(a, b) {
  * (another process reclaimed it and took a fresh lock in between), the fresh
  * lock is linked back into place and nothing is reclaimed.
  */
-function recordLockIsStale(lockPath, deps) {
+function recordLockIsStale(lockPath, deps, reclaimByAge = true) {
     const statSync = deps.statSync ?? ((p) => fs.statSync(p));
     const linkSync = deps.linkSync ?? fs.linkSync.bind(fs);
     const before = statSync(lockPath);
@@ -199,7 +199,7 @@ function recordLockIsStale(lockPath, deps) {
     const mtimeAge = now - before.mtimeMs;
     const age = Number.isFinite(ts) ? Math.max(now - ts, mtimeAge) : mtimeAge;
     const stale = (pidKnown && sameHost && pid !== process.pid && !lockOwnerAlive(pid)) ||
-        age > lockStaleMs();
+        (reclaimByAge && age > lockStaleMs());
     if (!stale)
         return false;
     const parked = `${lockPath}.stale.${process.pid}.${randomBytes(6).toString("hex")}`;
@@ -243,7 +243,7 @@ function recordLockIsStale(lockPath, deps) {
     removeParked();
     return reclaimed;
 }
-function withRecordLock(recordPath, deps, fn, timeoutMs = LOCK_TIMEOUT_MS) {
+function withRecordLock(recordPath, deps, fn, timeoutMs = LOCK_TIMEOUT_MS, reclaimByAge = true) {
     const lockPath = lockPathFor(recordPath);
     const statSync = deps.statSync ?? ((p) => fs.statSync(p));
     const fstatSync = deps.fstatSync ?? ((fd) => fs.fstatSync(fd));
@@ -295,7 +295,7 @@ function withRecordLock(recordPath, deps, fn, timeoutMs = LOCK_TIMEOUT_MS) {
                 throw new LanesError("store_lock_timeout", `Timed out waiting for lock ${lockPath}`, { path: lockPath });
             }
             try {
-                if (recordLockIsStale(lockPath, deps))
+                if (recordLockIsStale(lockPath, deps, reclaimByAge))
                     continue;
             }
             catch (statErr) {
@@ -309,12 +309,12 @@ function withRecordLock(recordPath, deps, fn, timeoutMs = LOCK_TIMEOUT_MS) {
     }
 }
 /** Test seam: run withRecordLock with overridden deps and a shorter timeout. */
-export function withRecordLockForTests(recordPath, overrides, fn, timeoutMs) {
-    return withRecordLock(recordPath, { ...defaultStoreDeps(), ...overrides }, fn, timeoutMs);
+export function withRecordLockForTests(recordPath, overrides, fn, timeoutMs, reclaimByAge = true) {
+    return withRecordLock(recordPath, { ...defaultStoreDeps(), ...overrides }, fn, timeoutMs, reclaimByAge);
 }
 /** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
-export function withLaneRecordFileLock(recordPath, fn) {
-    return withRecordLock(recordPath, defaultStoreDeps(), fn);
+export function withLaneRecordFileLock(recordPath, fn, options = {}) {
+    return withRecordLock(recordPath, defaultStoreDeps(), fn, LOCK_TIMEOUT_MS, options.reclaimByAge ?? true);
 }
 function readJsonFile(filePath, deps) {
     let text;

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/lib/windows/ps1-shims.d.ts

@@ -0,0 +1,60 @@
+/** hq-cli's own bins and the package file each npm launcher runs. */
+export declare const HQ_CLI_BINS: Readonly<Record<string, string>>;
+/**
+ * True when `content` is npm's (cmd-shim) PowerShell launcher for the hq-cli
+ * bin `bin`. The launcher resolves its own folder, runs node on
+ * `$basedir/node_modules/@indigoai-us/hq-cli/<entry>` and exits with node's
+ * code. Either slash direction is accepted.
+ */
+export declare function isNpmGeneratedHqCliPs1Shim(content: string, bin: string): boolean;
+export interface Ps1ShimFs {
+    readFile: (file: string) => string;
+    remove: (file: string) => void;
+}
+/** The npm-generated hq-cli `.ps1` launchers present in `binDir`. */
+export declare function findHqCliPs1Shims(binDir: string, io?: Ps1ShimFs): string[];
+export interface RemovePs1ShimsResult {
+    /** Launchers removed by this call. */
+    removed: string[];
+    /** `.ps1` files with an hq-cli bin name that are not npm's launcher. */
+    kept: string[];
+    /** Launchers that could not be removed, with the reason. */
+    failed: Array<{
+        file: string;
+        reason: string;
+    }>;
+}
+/**
+ * Remove the npm-generated `.ps1` launchers for hq-cli's bins from `binDir`
+ * (the npm global prefix on Windows). Safe to run again: a missing file is
+ * not an error. Never touches another package's `.ps1` or a hand-written one.
+ */
+export declare function removeHqCliPs1Shims(binDir: string, io?: Ps1ShimFs): RemovePs1ShimsResult;
+/**
+ * True when the effective execution policy blocks npm's unsigned launcher.
+ * `Undefined` as the effective policy means no scope set one, which Windows
+ * client editions treat as `Restricted`.
+ */
+export declare function policyBlocksUnsignedScripts(policy: string): boolean;
+export type ExecutionPolicyRun = () => {
+    status: number | null;
+    stdout: string;
+};
+/**
+ * Read the current user's effective PowerShell execution policy. Read-only:
+ * it runs `Get-ExecutionPolicy` and never sets anything. Null when
+ * PowerShell could not be run or printed nothing usable.
+ */
+export declare function readExecutionPolicy(run?: ExecutionPolicyRun): string | null;
+/**
+ * Postinstall entry: after a global npm install on Windows, remove hq-cli's
+ * `.ps1` launchers from the prefix holding `packageDir`. Acts only when the
+ * package sits at `<prefix>/node_modules/@indigoai-us/hq-cli`, npm's Windows
+ * global layout. Null when it did nothing. npm 11.16+ may skip lifecycle
+ * scripts, so `hq doctor` reports any launcher left behind.
+ */
+export declare function removePs1ShimsAfterNpmInstall(packageDir: string, opts: {
+    platform: NodeJS.Platform;
+    global: boolean;
+}, io?: Ps1ShimFs): RemovePs1ShimsResult | null;
+//# sourceMappingURL=ps1-shims.d.ts.map

package/dist/lib/windows/ps1-shims.js

@@ -0,0 +1,152 @@
+/**
+ * npm writes three launchers for every global bin on Windows: `hq`, `hq.cmd`
+ * and `hq.ps1`. PowerShell prefers `hq.ps1`, and under the default
+ * `Restricted` execution policy it refuses to run it ("running scripts is
+ * disabled on this system", UnauthorizedAccess). `hq.cmd` works under every
+ * policy, so hq-cli removes its own `.ps1` launchers and PowerShell falls
+ * through to `hq.cmd`.
+ *
+ * Only a file whose content is npm's generated launcher for an hq-cli bin is
+ * removed. A `.ps1` written by a person or another package is left alone. The
+ * execution policy is read only, never changed.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+/** hq-cli's own bins and the package file each npm launcher runs. */
+export const HQ_CLI_BINS = {
+    hq: "dist/index.js",
+    "hq-auth-refresh": "dist/bin/hq-auth-refresh.js",
+};
+const PACKAGE_PATH = "node_modules/@indigoai-us/hq-cli/";
+/**
+ * True when `content` is npm's (cmd-shim) PowerShell launcher for the hq-cli
+ * bin `bin`. The launcher resolves its own folder, runs node on
+ * `$basedir/node_modules/@indigoai-us/hq-cli/<entry>` and exits with node's
+ * code. Either slash direction is accepted.
+ */
+export function isNpmGeneratedHqCliPs1Shim(content, bin) {
+    const entry = HQ_CLI_BINS[bin];
+    if (!entry)
+        return false;
+    const text = content.replace(/\r\n/g, "\n").replace(/\\/g, "/");
+    if (!text.startsWith("#!/usr/bin/env pwsh\n"))
+        return false;
+    if (!text.includes("$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent"))
+        return false;
+    if (!text.trimEnd().endsWith("exit $ret"))
+        return false;
+    return text.includes(`"$basedir/${PACKAGE_PATH}${entry}"`);
+}
+const realFs = {
+    readFile: (file) => fs.readFileSync(file, "utf8"),
+    remove: (file) => fs.rmSync(file, { force: true }),
+};
+function isMissing(error) {
+    const code = error?.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/** The npm-generated hq-cli `.ps1` launchers present in `binDir`. */
+export function findHqCliPs1Shims(binDir, io = realFs) {
+    const found = [];
+    for (const bin of Object.keys(HQ_CLI_BINS)) {
+        const file = path.join(binDir, `${bin}.ps1`);
+        let content;
+        try {
+            content = io.readFile(file);
+        }
+        catch {
+            continue;
+        }
+        if (isNpmGeneratedHqCliPs1Shim(content, bin))
+            found.push(file);
+    }
+    return found;
+}
+/**
+ * Remove the npm-generated `.ps1` launchers for hq-cli's bins from `binDir`
+ * (the npm global prefix on Windows). Safe to run again: a missing file is
+ * not an error. Never touches another package's `.ps1` or a hand-written one.
+ */
+export function removeHqCliPs1Shims(binDir, io = realFs) {
+    const result = { removed: [], kept: [], failed: [] };
+    for (const bin of Object.keys(HQ_CLI_BINS)) {
+        const file = path.join(binDir, `${bin}.ps1`);
+        let content;
+        try {
+            content = io.readFile(file);
+        }
+        catch (error) {
+            if (!isMissing(error)) {
+                result.failed.push({ file, reason: error instanceof Error ? error.message : String(error) });
+            }
+            continue;
+        }
+        if (!isNpmGeneratedHqCliPs1Shim(content, bin)) {
+            result.kept.push(file);
+            continue;
+        }
+        try {
+            io.remove(file);
+            result.removed.push(file);
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            result.failed.push({ file, reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return result;
+}
+/** Policies under which PowerShell refuses to run an unsigned local `.ps1`. */
+const BLOCKING_POLICIES = new Set(["restricted", "allsigned", "undefined"]);
+/**
+ * True when the effective execution policy blocks npm's unsigned launcher.
+ * `Undefined` as the effective policy means no scope set one, which Windows
+ * client editions treat as `Restricted`.
+ */
+export function policyBlocksUnsignedScripts(policy) {
+    return BLOCKING_POLICIES.has(policy.trim().toLowerCase());
+}
+function defaultPolicyRun() {
+    const run = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "Get-ExecutionPolicy"], { encoding: "utf8", windowsHide: true, timeout: 15_000 });
+    return { status: run.status, stdout: typeof run.stdout === "string" ? run.stdout : "" };
+}
+/**
+ * Read the current user's effective PowerShell execution policy. Read-only:
+ * it runs `Get-ExecutionPolicy` and never sets anything. Null when
+ * PowerShell could not be run or printed nothing usable.
+ */
+export function readExecutionPolicy(run = defaultPolicyRun) {
+    try {
+        const { status, stdout } = run();
+        if (status !== 0)
+            return null;
+        const policy = stdout.trim().split(/\s+/).pop() ?? "";
+        return /^[A-Za-z]+$/.test(policy) ? policy : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Postinstall entry: after a global npm install on Windows, remove hq-cli's
+ * `.ps1` launchers from the prefix holding `packageDir`. Acts only when the
+ * package sits at `<prefix>/node_modules/@indigoai-us/hq-cli`, npm's Windows
+ * global layout. Null when it did nothing. npm 11.16+ may skip lifecycle
+ * scripts, so `hq doctor` reports any launcher left behind.
+ */
+export function removePs1ShimsAfterNpmInstall(packageDir, opts, io = realFs) {
+    if (opts.platform !== "win32" || !opts.global)
+        return null;
+    const dir = path.resolve(packageDir);
+    const scope = path.dirname(dir);
+    const nodeModules = path.dirname(scope);
+    if (path.basename(dir).toLowerCase() !== "hq-cli" ||
+        path.basename(scope).toLowerCase() !== "@indigoai-us" ||
+        path.basename(nodeModules).toLowerCase() !== "node_modules") {
+        return null;
+    }
+    return removeHqCliPs1Shims(path.dirname(nodeModules), io);
+}
+//# sourceMappingURL=ps1-shims.js.map

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;
 /**