@indigoai-us/hq-cli 5.345.159 → 5.345.160

package/dist/hq-cloud-sync-runner/package.json

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.97","bundleSha256":"7cb110257acf96c8d91c57f238f7f01be43620ed66ae28dfe74dcc972be64153","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.98","bundleSha256":"70fe5497fffdbb678370515f8b7df63438d7a59a95467102307459e78f9f4715","formatVersion":1}

package/dist/lib/billing/plan-limit-refusals.d.ts

@@ -18,6 +18,12 @@
  * stops re-sending paused keys. The `path`/`paths`/`count` reads below consume
  * that event; the `error`-message parsing stays for runners older than
  * 6.18.17.
+ *
+ * US-024: the server's sentence wins. A `plan-limit` event carries the 402
+ * body's `message` (for a usage pause, the `usagePause` message hq-pro writes
+ * for the person who hit it), and a runner that forwards `usagePause` gives
+ * its message and `actionUrl` directly. The CLI adds no plan name and labels
+ * the link `Billing:`, never "Upgrade".
  */
 import { type SyncProgressEvent } from "@indigoai-us/hq-cloud";
 /** What one push leg was refused. `null` from the tracker means nothing was. */
@@ -29,10 +35,12 @@ export interface PlanLimitRefusalSummary {
     count: number;
     /** Vault-relative paths the runner named, de-duplicated, in report order. */
     paths: string[];
-    /** Server sentence from a refused file's error, when one was carried. */
+    /** Server sentence (usage pause message, event message, or a refused file's error). */
     message?: string;
-    /** Server-selected (or company billing fallback) upgrade link. */
+    /** Server-selected (or company billing fallback) billing link. */
     upgradeUrl?: string;
+    /** True when the server said this is a usage pause (`usagePause`). */
+    usagePause?: boolean;
 }
 export interface PlanLimitRefusalTracker {
     observe(event: SyncProgressEvent): void;
@@ -57,9 +65,11 @@ export declare function createPlanLimitRefusalTracker(opts?: {
 export declare function trackingProgressRecorder(tracker: PlanLimitRefusalTracker, company: string | null): (event: SyncProgressEvent) => void;
 /** Add a later leg's refusals to an earlier total. */
 export declare function mergePlanLimitRefusals(a: PlanLimitRefusalSummary | null | undefined, b: PlanLimitRefusalSummary | null | undefined): PlanLimitRefusalSummary | null;
+/** The sentence when the server sent none. Names no plan. */
+export declare const REFUSAL_FALLBACK_SENTENCE = "New files are paused for this account. Open its Billing page to see why.";
 /**
  * Plain lines describing a refusal: what was not uploaded, why, and the
- * upgrade link. Colour and the leading status line are the caller's.
+ * billing link. Colour and the leading status line are the caller's.
  */
 export declare function renderPlanLimitRefusalLines(summary: PlanLimitRefusalSummary, indent?: string): string[];
 /** "1 new file" / "3 new files", or "new files" when only a notice said so. */

package/dist/lib/billing/plan-limit-refusals.js

@@ -18,9 +18,16 @@
  * stops re-sending paused keys. The `path`/`paths`/`count` reads below consume
  * that event; the `error`-message parsing stays for runners older than
  * 6.18.17.
+ *
+ * US-024: the server's sentence wins. A `plan-limit` event carries the 402
+ * body's `message` (for a usage pause, the `usagePause` message hq-pro writes
+ * for the person who hit it), and a runner that forwards `usagePause` gives
+ * its message and `actionUrl` directly. The CLI adds no plan name and labels
+ * the link `Billing:`, never "Upgrade".
  */
 import { createSyncProgressRecorder, } from "@indigoai-us/hq-cloud";
 import { planLimitUpgradeFallbackUrl } from "./plan-limit-upgrade-url.js";
+import { usagePauseFromBody } from "./usage-pause.js";
 /** Upgrade destination when neither the event nor the error named one. */
 const FALLBACK_UPGRADE_URL = "https://hq.computer/billing";
 const PLAN_LIMIT_CODE_TOKEN = /\bcode=(?:PLAN_LIMIT_EXCEEDED|PLAN_LIMIT_REACHED|plan_limit_reached)\b/;
@@ -72,6 +79,7 @@ export function createPlanLimitRefusalTracker(opts = {}) {
     let reportedCount = 0;
     let message;
     let upgradeUrl;
+    let usagePaused = false;
     const addPath = (value) => {
         if (typeof value === "string" && value && !paths.includes(value)) {
             paths.push(value);
@@ -82,7 +90,17 @@ export function createPlanLimitRefusalTracker(opts = {}) {
             const record = event;
             if (event.type === "plan-limit") {
                 noticeSeen = true;
+                const pause = usagePauseFromBody(record);
+                if (pause) {
+                    usagePaused = true;
+                    message = pause.message;
+                    if (pause.actionUrl)
+                        upgradeUrl = pause.actionUrl;
+                }
                 upgradeUrl ??= safeHttpsUrl(record.upgradeUrl);
+                if (typeof record.message === "string" && record.message.trim()) {
+                    message ??= record.message.trim();
+                }
                 addPath(record.path);
                 if (Array.isArray(record.paths))
                     record.paths.forEach(addPath);
@@ -111,6 +129,7 @@ export function createPlanLimitRefusalTracker(opts = {}) {
                 paths: [...paths],
                 ...(message ? { message } : {}),
                 ...(url ? { upgradeUrl: url } : {}),
+                ...(usagePaused ? { usagePause: true } : {}),
             };
         },
     };
@@ -141,22 +160,26 @@ export function mergePlanLimitRefusals(a, b) {
             paths.push(p);
     const message = a.message ?? b.message;
     const upgradeUrl = a.upgradeUrl ?? b.upgradeUrl;
+    const usagePause = a.usagePause === true || b.usagePause === true;
     return {
         count: a.count + b.count,
         paths,
         ...(message ? { message } : {}),
         ...(upgradeUrl ? { upgradeUrl } : {}),
+        ...(usagePause ? { usagePause } : {}),
     };
 }
 /** How many named paths to print before summarising the rest. */
 const MAX_LISTED_PATHS = 20;
+/** The sentence when the server sent none. Names no plan. */
+export const REFUSAL_FALLBACK_SENTENCE = "New files are paused for this account. Open its Billing page to see why.";
 /**
  * Plain lines describing a refusal: what was not uploaded, why, and the
- * upgrade link. Colour and the leading status line are the caller's.
+ * billing link. Colour and the leading status line are the caller's.
  */
 export function renderPlanLimitRefusalLines(summary, indent = "  ") {
     const lines = [];
-    lines.push(`${indent}${summary.message ?? "New files are paused by your plan limit."}`);
+    lines.push(`${indent}${summary.message ?? REFUSAL_FALLBACK_SENTENCE}`);
     if (summary.paths.length > 0) {
         lines.push(`${indent}Not uploaded:`);
         for (const p of summary.paths.slice(0, MAX_LISTED_PATHS)) {
@@ -170,7 +193,7 @@ export function renderPlanLimitRefusalLines(summary, indent = "  ") {
         lines.push(`${indent}New files stay on this machine and were not uploaded.`);
     }
     if (summary.upgradeUrl)
-        lines.push(`${indent}Upgrade: ${summary.upgradeUrl}`);
+        lines.push(`${indent}Billing: ${summary.upgradeUrl}`);
     return lines;
 }
 /** "1 new file" / "3 new files", or "new files" when only a notice said so. */

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

@@ -3,6 +3,14 @@ export interface PlanLimitUpgradeUrlChoices {
     nestedUrl?: string | null;
     legacyUrl: string;
 }
+/**
+ * The console's self-serve switch to usage pricing for one company. While HQ
+ * Workforce is closed to companies not already on it (hq-pro
+ * `billing.legacy-plans-closed`, owner decision 2026-10-19) this is where an
+ * upgrade leads; the Workforce checkout refuses. Null when no console origin
+ * can be derived; without a slug the generic billing page.
+ */
+export declare function usageSwitchPageUrl(companySlug?: string): string | null;
 /** Resolve and attribute the final selected company billing destination. */
 export declare function selectPlanLimitUpgradeUrl(companySlug: string | undefined, choices: PlanLimitUpgradeUrlChoices): string;
 export declare function withCliLimitEntrySurface(value: string): string;

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

@@ -11,6 +11,24 @@ function companyBillingUrl(companySlug) {
         : "/billing";
     return `${origin}${route}`;
 }
+/**
+ * The console's self-serve switch to usage pricing for one company. While HQ
+ * Workforce is closed to companies not already on it (hq-pro
+ * `billing.legacy-plans-closed`, owner decision 2026-10-19) this is where an
+ * upgrade leads; the Workforce checkout refuses. Null when no console origin
+ * can be derived; without a slug the generic billing page.
+ */
+export function usageSwitchPageUrl(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/usage-switch?entrySurface=cli_limit`
+        : "/billing";
+    return `${origin}${route}`;
+}
 /** Resolve and attribute the final selected company billing destination. */
 export function selectPlanLimitUpgradeUrl(companySlug, choices) {
     const topLevelUrl = choices.topLevelUrl?.trim() || undefined;

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

@@ -17,6 +17,13 @@
  * Copy rule (US-036): no string a customer reads may contain "locked" or
  * "read-only". `plan-lock.test.ts` scans every rendered string for both.
  *
+ * Copy rule (US-024): the flat plans are closed, so nothing here offers the
+ * Workforce plan, its price or the free month, and nothing says "Upgrade".
+ * The plan is named (Starter) only when hq-pro said the company is on an
+ * earlier plan (`billingState` or `pricingPlan: "current"`); an unknown plan
+ * gets copy that names no plan, and the way out besides trimming is the
+ * switch to usage pricing or the company's Billing page.
+ *
  * An absent field is UNKNOWN, so nothing here ever infers over-limit from
  * missing data (hq-absent-field-never-means-constraining-value).
  */
@@ -58,8 +65,18 @@ export interface PlanLimitStatus {
      * which keeps the legacy copy.
      */
     pricingPlan?: PricingPlan;
+    /**
+     * True when hq-pro says HQ Workforce is closed to this company (hq-flags
+     * `billing.legacy-plans-closed`, owner decision 2026-10-19). `upgradeUrl`
+     * is then the console's usage-pricing switch page, the free month never
+     * stands, and the renderers offer the switch instead of a Workforce
+     * upgrade. Absent keeps the legacy copy (older servers).
+     */
+    legacyPlansClosed?: boolean;
     checkedAt: string;
 }
+/** The way out while HQ Workforce is closed. Copy lives in ONE place. */
+export declare const USAGE_SWITCH_LABEL = "Switch to usage pricing";
 /** Starter member cap quoted when the server did not send a users.limit. */
 export declare const STARTER_MEMBER_TARGET = 5;
 /**
@@ -71,10 +88,8 @@ export declare const STARTER_INTEGRATION_TARGET = 3;
 export declare const STARTER_SECRET_TARGET = 10;
 /** Starter agent cap quoted when the server did not send an agents.limit. */
 export declare const STARTER_AGENT_TARGET = 0;
-/** Upgrade destination quoted when the server did not send one. */
+/** Billing destination quoted when the server did not send one. */
 export declare const DEFAULT_UPGRADE_URL = "https://hq.computer/billing";
-/** The paid plan the nag sends owners to. Copy lives in ONE place. */
-export declare const WORKFORCE_PLAN_LABEL = "HQ Workforce ($500/mo)";
 /**
  * Pick the membership row for `companySlug` (or `cmp_…` uid) out of a decoded
  * `/membership/me` body. No matching row is UNKNOWN. Does not read `planLock`.
@@ -133,9 +148,10 @@ export declare function renderPlanLimitNotice(status: PlanLimitStatus, opts?: {
  */
 export declare function renderPlanLimitLine(status: PlanLimitStatus): string;
 /**
- * The `Plan: …` orientation line. Starter only: a paid or enterprise
- * workspace — and an UNKNOWN plan — gets no line at all. A usage-pricing
- * company gets the usage line instead.
+ * The `Plan: …` orientation line. Starter only, and only when hq-pro said the
+ * company is on an earlier plan: a paid or enterprise workspace gets no line,
+ * and an UNKNOWN pricing plan names no plan. A usage-pricing company gets the
+ * usage line instead.
  */
 export declare function renderPlanLine(status: PlanLimitStatus): string | null;
 /**

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

@@ -17,6 +17,13 @@
  * Copy rule (US-036): no string a customer reads may contain "locked" or
  * "read-only". `plan-lock.test.ts` scans every rendered string for both.
  *
+ * Copy rule (US-024): the flat plans are closed, so nothing here offers the
+ * Workforce plan, its price or the free month, and nothing says "Upgrade".
+ * The plan is named (Starter) only when hq-pro said the company is on an
+ * earlier plan (`billingState` or `pricingPlan: "current"`); an unknown plan
+ * gets copy that names no plan, and the way out besides trimming is the
+ * switch to usage pricing or the company's Billing page.
+ *
  * An absent field is UNKNOWN, so nothing here ever infers over-limit from
  * missing data (hq-absent-field-never-means-constraining-value).
  */
@@ -24,7 +31,7 @@ import chalk from "chalk";
 import { diagnosticsEnabled } from "../diagnostics.js";
 import { vaultApiFetch } from "../../utils/vault-api.js";
 import { parseFreeMonth } from "./free-month.js";
-import { selectPlanLimitUpgradeUrl } from "./plan-limit-upgrade-url.js";
+import { selectPlanLimitUpgradeUrl, usageSwitchPageUrl, } from "./plan-limit-upgrade-url.js";
 import { fetchCompanyPricingPlan, isUsageOnly, pricingPlanFromBody, pricingPlanFromMembership, usageOnlyPlanLine, usageOnlyUpgradeLines, } from "./usage-only.js";
 // The free-month parser lives in a leaf module so the plan-gate 402 decoder can
 // share it without importing the HTTP layer; re-exported so existing callers
@@ -41,6 +48,8 @@ export const PLAN_LIMIT_REASONS = [
     "secrets",
     "agents",
 ];
+/** The way out while HQ Workforce is closed. Copy lives in ONE place. */
+export const USAGE_SWITCH_LABEL = "Switch to usage pricing";
 /** Starter member cap quoted when the server did not send a users.limit. */
 export const STARTER_MEMBER_TARGET = 5;
 /**
@@ -52,10 +61,8 @@ export const STARTER_INTEGRATION_TARGET = 3;
 export const STARTER_SECRET_TARGET = 10;
 /** Starter agent cap quoted when the server did not send an agents.limit. */
 export const STARTER_AGENT_TARGET = 0;
-/** Upgrade destination quoted when the server did not send one. */
+/** Billing destination quoted when the server did not send one. */
 export const DEFAULT_UPGRADE_URL = "https://hq.computer/billing";
-/** The paid plan the nag sends owners to. Copy lives in ONE place. */
-export const WORKFORCE_PLAN_LABEL = "HQ Workforce ($500/mo)";
 function finiteNumber(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
@@ -157,6 +164,17 @@ function selectUpgradeUrl(body, companySlug) {
     const nestedUrl = typeof nested?.upgradeUrl === "string" && nested.upgradeUrl.trim().length > 0
         ? nested.upgradeUrl.trim()
         : undefined;
+    // While HQ Workforce is closed the way out is the usage-pricing switch, not
+    // the company billing page the generated URL would land on. Build it from
+    // the slug when known; otherwise keep the server's own switch URL.
+    if (rec?.legacyPlansClosed === true) {
+        const slug = companySlug?.trim();
+        return (slug ? usageSwitchPageUrl(slug) : undefined) ??
+            topLevelUrl ??
+            nestedUrl ??
+            usageSwitchPageUrl(undefined) ??
+            DEFAULT_UPGRADE_URL;
+    }
     return selectPlanLimitUpgradeUrl(companySlug, {
         topLevelUrl,
         nestedUrl,
@@ -210,6 +228,7 @@ function statusFromUsage(companySlug, companyUid, body, upgradeCompanySlug) {
         upgradeUrl: selectUpgradeUrl(body, upgradeCompanySlug),
         freeMonth: parseFreeMonth(rec?.freeMonth),
         plan: selectPlan(body) ?? undefined,
+        ...(rec?.legacyPlansClosed === true ? { legacyPlansClosed: true } : {}),
         checkedAt: new Date().toISOString(),
     }, pricingPlan);
 }
@@ -295,6 +314,10 @@ export async function fetchPlanLimitStatus(token, companyRef, opts = {}) {
         return null;
     }
 }
+/** True when hq-pro said the company is on an earlier (flat) plan. */
+function knownEarlierPlan(status) {
+    return status.pricingPlan === "current";
+}
 /** Why the workspace is over, one clause per reason. */
 export function reasonLabel(reason) {
     switch (reason) {
@@ -305,7 +328,7 @@ export function reasonLabel(reason) {
         case "secrets":
             return "too many secrets";
         case "agents":
-            return "agents are not included on Starter";
+            return "agents are not included";
     }
 }
 function usageTarget(reason, status) {
@@ -357,7 +380,7 @@ function reasonDetail(reason, status) {
                 ? `${row.used} of ${target} secrets`
                 : `over its ${target}-secret limit`;
         case "agents":
-            return "agents are not included on Starter";
+            return "agents are not included";
     }
 }
 function usageLine(reason, status) {
@@ -368,20 +391,20 @@ function usageLine(reason, status) {
             const members = row ?? status.members;
             return members
                 ? `  Members: ${members.used} of ${target}.`
-                : `  Members allowed on Starter: ${target}.`;
+                : `  Members allowed: ${target}.`;
         }
         case "integrations":
             return row
                 ? `  Integrations: ${row.used} of ${target}.`
-                : `  Integrations allowed on Starter: ${target}.`;
+                : `  Integrations allowed: ${target}.`;
         case "secrets":
             return row
                 ? `  Secrets: ${row.used} of ${target}.`
-                : `  Secrets allowed on Starter: ${target}.`;
+                : `  Secrets allowed: ${target}.`;
         case "agents":
             return row
                 ? `  Agents: ${row.used} of ${target}.`
-                : `  Agents allowed on Starter: ${target}.`;
+                : `  Agents allowed: ${target}.`;
     }
 }
 /**
@@ -409,15 +432,17 @@ function capitalize(text) {
  * about a dimension nobody measured.
  */
 export function renderPlanLimitNotice(status, opts = {}) {
-    const { companySlug, freeMonth } = status;
+    const { companySlug } = status;
     const lines = [];
     if (isUsageOnly(status.pricingPlan)) {
         return [`${companySlug}:`, ...usageOnlyUpgradeLines().map((l) => `  ${l}`)].join("\n");
     }
-    lines.push(`HQ Starter — ${companySlug} is over its plan limits.`);
+    lines.push(knownEarlierPlan(status)
+        ? `HQ Starter — ${companySlug} is over its Starter limits.`
+        : `${companySlug} is over its limits.`);
     const reasons = status.reasons.length
         ? status.reasons.map(reasonLabel).join("; ")
-        : "over the Starter plan limits";
+        : "over its limits";
     lines.push(`  Why: ${reasons}.`);
     for (const reason of status.reasons) {
         lines.push(usageLine(reason, status));
@@ -426,21 +451,20 @@ export function renderPlanLimitNotice(status, opts = {}) {
     lines.push(HARD_STOP_SENTENCE_LINES[1]);
     const remedy = status.reasons.length
         ? status.reasons.map((reason) => reasonRemedy(reason, status)).join(", and ")
-        : "come back under the Starter plan limits";
-    const freeMonthUrl = freeMonth?.url;
-    const hasFreeMonth = Boolean(freeMonth?.eligible && freeMonthUrl);
-    if (hasFreeMonth) {
-        lines.push("  Three ways to sort it:");
-        lines.push(`    1. Start your free month — add a card, first month free: ${freeMonthUrl}`);
-        lines.push(`    2. ${capitalize(remedy)}.`);
-        lines.push(`    3. Upgrade to ${WORKFORCE_PLAN_LABEL}.`);
+        : "come back under its limits";
+    // The flat plans are closed: no Workforce offer and no free month (it led
+    // to the closed checkout). The second way out is the switch to usage
+    // pricing when the server said the company is on an earlier plan or that
+    // the flat plans are closed to it; otherwise the company's Billing page.
+    lines.push("  Two ways to sort it:");
+    lines.push(`    1. ${capitalize(remedy)}.`);
+    if (status.legacyPlansClosed || knownEarlierPlan(status)) {
+        lines.push(`    2. ${USAGE_SWITCH_LABEL}: no plan fee, and these limits stop applying.`);
     }
     else {
-        lines.push("  Two ways to sort it:");
-        lines.push(`    1. ${capitalize(remedy)}.`);
-        lines.push(`    2. Upgrade to ${WORKFORCE_PLAN_LABEL}.`);
+        lines.push("    2. Open the company's Billing page.");
     }
-    lines.push(`  Upgrade: ${status.upgradeUrl}`);
+    lines.push(`  ${status.legacyPlansClosed ? "Switch" : "Billing"}: ${status.upgradeUrl}`);
     if (opts.inviteTeammateEnabled === true &&
         status.plan === "free" &&
         status.over &&
@@ -459,18 +483,22 @@ export function renderPlanLimitLine(status) {
     }
     const detail = status.reasons.length
         ? status.reasons.map((reason) => reasonDetail(reason, status)).join("; ")
-        : "over the Starter plan limits";
-    return (`Company ${status.companySlug} is over its Starter limits (${detail}). ` +
+        : "over its limits";
+    const limits = knownEarlierPlan(status) ? "its Starter limits" : "its limits";
+    return (`Company ${status.companySlug} is over ${limits} (${detail}). ` +
         `New files and new secrets are paused until this is sorted: ${status.upgradeUrl}`);
 }
 /**
- * The `Plan: …` orientation line. Starter only: a paid or enterprise
- * workspace — and an UNKNOWN plan — gets no line at all. A usage-pricing
- * company gets the usage line instead.
+ * The `Plan: …` orientation line. Starter only, and only when hq-pro said the
+ * company is on an earlier plan: a paid or enterprise workspace gets no line,
+ * and an UNKNOWN pricing plan names no plan. A usage-pricing company gets the
+ * usage line instead.
  */
 export function renderPlanLine(status) {
     if (isUsageOnly(status.pricingPlan))
         return usageOnlyPlanLine();
+    if (!knownEarlierPlan(status))
+        return status.over ? "Plan: over its limits" : null;
     if (status.over)
         return "Plan: Starter — over its limits";
     if (status.plan !== "free")

package/dist/lib/billing/usage-cost.d.ts

@@ -13,6 +13,8 @@
  *   - optionally, the live cloud file-history listing `hq storage status`
  *     uses, to split storage into current files and old versions and to see a
  *     prune right away (Storage Lens, behind usage-limits, updates daily).
+ *     With the usage statement, the listing is a separate current-storage
+ *     breakdown only; the statement's month-average storage meter is billed.
  * usage-limits also answers `vaults` when the server counts them; without it
  * the vault meter is `not-available`.
  * The call-count meters (syncs, gateway calls, HQ MCP calls, agent runs) have
@@ -45,6 +47,16 @@ export interface MeterReading {
     /** In billed units (GB for storage). Null unless measured. */
     value: number | null;
     state: MeterState;
+    /**
+     * The server's own priced amounts for this line (usage statement only).
+     * When present they are the bill: the statement is what is invoiced to the
+     * cent, so the line is never re-priced from the rate card.
+     */
+    accrued?: {
+        monthToDateUsd: number;
+        projectedUsd: number;
+        waived?: boolean;
+    };
 }
 export interface StorageSplit {
     /** Bytes in current files. */
@@ -60,7 +72,7 @@ export interface StorageSplit {
 export interface MonthUsage {
     scope: UsageScope;
     /** Which source answered; lets a reader tell interim numbers from the rollup. */
-    source: "usage-limits" | "daily-rollup";
+    source: "usage-statement" | "usage-limits" | "daily-rollup";
     /** Month-to-date window, UTC. */
     period: {
         start: string;
@@ -71,6 +83,8 @@ export interface MonthUsage {
     storage?: StorageSplit;
     /** True when the account's usage trial is running (meters waived in trial bill $0). Absent = unknown. */
     trialActive?: boolean;
+    /** The included usage the usage statement applied. Absent: use the rate card's. */
+    allowanceUsd?: number;
 }
 /** One way to read a month of usage. The rollup becomes a second implementation. */
 export interface MonthUsageSource {
@@ -119,6 +133,14 @@ export declare function meterReadingsFromDailyRows(rows: readonly UsageDailyRowL
  * {@link readMonthUsage} once that route ships; the company scope only.
  */
 export declare function dailyRollupSource(fetchRows: (scope: UsageScope, from: string, to: string) => Promise<readonly UsageDailyRowLike[] | null>): MonthUsageSource;
+export declare function meterReadingsFromStatement(body: unknown): MeterReading[] | null;
+/**
+ * The usage statement as a source (`GET /v1/billing/usage`, US-015). The
+ * company statement is owner-gated on the server; a person statement is the
+ * caller's own. `fetchStatement` resolves the decoded body, or null when the
+ * server did not answer.
+ */
+export declare function usageStatementSource(fetchStatement: (scope: UsageScope) => Promise<unknown | null>): MonthUsageSource;
 /**
  * The one function every caller uses to read a month of usage. Switch the
  * default source here when the US-005 rollup has a read route.
@@ -151,7 +173,7 @@ export interface UsageBill {
     daysElapsed: number;
     daysInMonth: number;
 }
-export declare function computeBill(usage: MonthUsage, rates?: readonly UsageMeterRate[], allowanceUsd?: number): UsageBill;
+export declare function computeBill(usage: MonthUsage, rates?: readonly UsageMeterRate[], cardAllowanceUsd?: number): UsageBill;
 export type FixId = "prune-old-versions" | "remove-unused-secrets" | "exclude-folders" | "turn-sync-off";
 /**
  * A fix is a pair of command lists. `preview` only reads (dry runs, listings);

package/dist/lib/billing/usage-cost.js

@@ -13,6 +13,8 @@
  *   - optionally, the live cloud file-history listing `hq storage status`
  *     uses, to split storage into current files and old versions and to see a
  *     prune right away (Storage Lens, behind usage-limits, updates daily).
+ *     With the usage statement, the listing is a separate current-storage
+ *     breakdown only; the statement's month-average storage meter is billed.
  * usage-limits also answers `vaults` when the server counts them; without it
  * the vault meter is `not-available`.
  * The call-count meters (syncs, gateway calls, HQ MCP calls, agent runs) have
@@ -145,6 +147,83 @@ export function dailyRollupSource(fetchRows) {
         },
     };
 }
+/** Statement line key (hq-pro `UsageStatementLine.key`) -> rate-card key. */
+const STATEMENT_KEYS = new Set(BUNDLED_USAGE_METER_RATES.map(({ key }) => key));
+/**
+ * Meter readings from a `GET /v1/billing/usage` statement body (hq-pro
+ * src/billing/usage-statement.ts, US-006). `usage` is the natural amount:
+ * counters are the month's total, gauges the mean daily level. Storage comes
+ * in bytes and is converted with the statement's own `storageBytesPerGb`.
+ * A line that is unavailable, not billed yet, or missing is `not-available`,
+ * never zero. Null when the body is not a statement.
+ */
+function centsField(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
+}
+export function meterReadingsFromStatement(body) {
+    const rec = body !== null && typeof body === "object" && !Array.isArray(body)
+        ? body
+        : null;
+    if (!rec || !Array.isArray(rec.lines))
+        return null;
+    const bytesPerGb = typeof rec.storageBytesPerGb === "number" && rec.storageBytesPerGb > 0
+        ? rec.storageBytesPerGb
+        : BYTES_PER_GB;
+    const byKey = new Map();
+    for (const raw of rec.lines) {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const line = raw;
+        if (typeof line.key !== "string" || !STATEMENT_KEYS.has(line.key))
+            continue;
+        const key = line.key;
+        const measured = line.status === "measured" || line.status === "partial";
+        const usage = line.usage;
+        if (!measured || typeof usage !== "number" || !Number.isFinite(usage) || usage < 0) {
+            byKey.set(key, { key, value: null, state: "not-available" });
+            continue;
+        }
+        const reading = { key, value: key === "storage" ? usage / bytesPerGb : usage, state: "measured" };
+        const cost = centsField(line.costCents);
+        const projected = centsField(line.projectedCostCents);
+        if (cost !== null && projected !== null) {
+            reading.accrued = {
+                monthToDateUsd: cost / 100,
+                projectedUsd: projected / 100,
+                ...(line.waived === true ? { waived: true } : {}),
+            };
+        }
+        byKey.set(key, reading);
+    }
+    return BUNDLED_USAGE_METER_RATES.map(({ key }) => byKey.get(key) ?? { key, value: null, state: "not-available" });
+}
+/**
+ * The usage statement as a source (`GET /v1/billing/usage`, US-015). The
+ * company statement is owner-gated on the server; a person statement is the
+ * caller's own. `fetchStatement` resolves the decoded body, or null when the
+ * server did not answer.
+ */
+export function usageStatementSource(fetchStatement) {
+    return {
+        name: "usage-statement",
+        async read(scope, now) {
+            const { start, end } = monthWindow(now);
+            const body = await fetchStatement(scope);
+            const meters = meterReadingsFromStatement(body);
+            if (meters === null) {
+                throw new Error("Could not read usage from HQ right now. Try again, or run `hq login` if you are signed out.");
+            }
+            const allowanceCents = centsField(body.allowanceCents);
+            return {
+                scope,
+                source: "usage-statement",
+                period: { start: start.toISOString(), end: end.toISOString(), asOf: now.toISOString() },
+                meters,
+                ...(allowanceCents !== null ? { allowanceUsd: allowanceCents / 100 } : {}),
+            };
+        },
+    };
+}
 /**
  * The one function every caller uses to read a month of usage. Switch the
  * default source here when the US-005 rollup has a read route.
@@ -159,8 +238,15 @@ export async function readMonthUsage(scope, deps, source = usageLimitsSource(dep
     const split = await deps.readStorageSplit(scope).catch(() => null);
     if (!split)
         return base;
-    // The live listing is fresher than the daily Storage Lens figure, so a prune
-    // shows up in the very next read.
+    // An accrued source (the usage statement, the daily rollup) bills storage as
+    // the month's average. That meter is authoritative: the live listing is a
+    // point-in-time figure, kept only as the separate `storage` breakdown that
+    // explains what is taking space. It never replaces or re-prices the meter.
+    if (base.source !== "usage-limits")
+        return { ...base, storage: split };
+    // usage-limits storage is itself a point-in-time reading (Storage Lens,
+    // updated daily). The live listing measures the same thing more freshly, so
+    // a prune shows up in the very next read.
     const liveGb = (split.currentBytes + split.oldVersionBytes) / BYTES_PER_GB;
     return {
         ...base,
@@ -169,7 +255,8 @@ export async function readMonthUsage(scope, deps, source = usageLimitsSource(dep
     };
 }
 const round2 = (n) => Math.round(n * 100) / 100;
-export function computeBill(usage, rates = BUNDLED_USAGE_METER_RATES, allowanceUsd = USAGE_MONTHLY_ALLOWANCE_USD) {
+export function computeBill(usage, rates = BUNDLED_USAGE_METER_RATES, cardAllowanceUsd = USAGE_MONTHLY_ALLOWANCE_USD) {
+    const allowanceUsd = usage.allowanceUsd ?? cardAllowanceUsd;
     const asOf = new Date(usage.period.asOf);
     const { start, end } = monthWindow(asOf);
     const dayMs = 86_400_000;
@@ -187,6 +274,19 @@ export function computeBill(usage, rates = BUNDLED_USAGE_METER_RATES, allowanceU
             incomplete = true;
             return { ...pick(rate), value: null, state: reading.state, monthToDateUsd: null, projectedUsd: null };
         }
+        if (reading.accrued) {
+            const { monthToDateUsd: m, projectedUsd: p, waived } = reading.accrued;
+            mtd += m;
+            projected += p;
+            return {
+                ...pick(rate),
+                value: reading.value,
+                state: "measured",
+                monthToDateUsd: round2(m),
+                projectedUsd: round2(p),
+                ...(waived ? { waivedInTrial: true } : {}),
+            };
+        }
         if (rate.waivedInTrial && usage.trialActive === true) {
             return { ...pick(rate), value: reading.value, state: "measured", monthToDateUsd: 0, projectedUsd: 0, waivedInTrial: true };
         }