@indigoai-us/hq-cli 5.345.159 → 5.345.160

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [5.345.160] — 2026-10-22
+- The bundled sync engine now uses hq-cloud 6.18.98. When HQ pauses an account because of usage, `hq sync` now shows the server's usage-pause message and a Billing link instead of a generic failure (hq-cloud #1036).
+- `hq billing usage` now shows the amounts on HQ's usage statement, which is what the invoice bills. Before this it re-priced the meters itself, so it could show a different figure than the statement, for example charging the vault fee during the trial when the statement waived it.
+- When HQ pauses an account because of usage (spend limit reached, card needed, or trial cap hit), `hq` now shows the server's own message and a Billing link, with no plan-limit or Upgrade wording and no old plan names (Starter, Workforce, Individual). This covers sync, skills, agent enroll, meetings, members, secrets, integrations and remote databases. `hq billing upgrade` now opens the usage-pricing switch page instead of a Workforce checkout. `hq billing usage` now shows the company's usage view, and tells a member to use `--personal` for their own usage. Plan and trial reads use the server's shared plan status when it is available, and older servers keep working as before. (US-024)
+
+- `hq files acl` and `hq access` show a path whose most-specific ACL row has no grants and is not open as locked by that row (`lockedBy` in `--json`), instead of as inheriting a broader `*` grant. An open empty row is not a lock: broader grants still apply. An empty ancestor row, whose open flag the server does not report, reads as locked unless that row is open.
+- `hq billing upgrade` no longer dead-ends on the closed HQ Workforce checkout. When hq-pro answers that Workforce is closed to the company (`workforce_closed_to_new_signups`), the command explains that the company stays on Starter unless it switches to usage pricing, says to add a card first with `hq billing checkout`, and opens the console's usage-switch page for the company (`--no-browser` prints it; `--json` returns `{ url, legacyPlansClosed: true, message }`). The open-checkout line no longer quotes a plan price. The over-limit notice (`hq whoami`) and the plan-limit refusal printed by `hq secrets`, `hq members` and sync now read hq-pro's `legacyPlansClosed` field: while Workforce is closed they offer "Switch to usage pricing" with the switch link and never the free Workforce month or an "Upgrade to HQ Workforce" line. Older servers keep today's wording.
+- `hq-hook` gains the US-021 bridge used by master-hook.sh: `hq-hook bridge-plan`
+  lists the registry hooks whose `hook-engine-port-<id>` flag is `shadow` or
+  `on`, `hq-hook bridge <id>` runs one hook natively (shadow compares with bash
+  and returns the bash result; on returns the native result; a missing port or
+  a declined payload falls back to bash), and `hq-hook --self-check` reports the
+  engine version and bridge schema. The local kill switch `HQ_HOOK_ENGINE=off`
+  or the file `~/.hq/hook-engine.off` forces bash before any flag is read.
+  Shadow comparisons are appended to `~/.hq/logs/hook-engine.jsonl` with hook
+  ids, hashes, exit codes and timings only.
+- `hq-hook run derive-trigger-facts` and `hq-hook run eval-trigger` are native
+  ports of the two policy-trigger helpers (US-008, first slice), byte-identical
+  to the bundled shell on the parity corpus, with git facts read in-process.
+- `hq core hook-engine-path` now runs the engine's `--self-check` before
+  printing its path, and writes `~/.hq/bin/hq-hook/current` so hooks can find
+  the pinned engine without starting Node. A binary that fails its self-check
+  exits non-zero and removes that pointer, keeping bash hooks active.
+
 ## [5.345.159] — 2026-10-22
 - `hq lanes link read` and `wait` now require the selected conductor session to own the requested link, preventing accidental cross-link report consumption while preserving explicit session resume/delegation and child inbox access.
 - `hq lanes resume` now uses the canonical lane ID after resolving a short ID. When low disk space queues a resume, it keeps the requested instruction for later admission and reports the lane as queued rather than started.

package/dist/command-catalog.generated.d.ts

@@ -1393,7 +1393,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly hidden: false;
     }, {
         readonly flags: "--company <slug>";
-        readonly description: "Also report this company's workspace plan state (Starter nag)";
+        readonly description: "Also report this company's billing and usage notice";
         readonly hidden: false;
     }];
     readonly subcommands: readonly [];
@@ -8478,7 +8478,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "upgrade";
-        readonly description: "Open Stripe Checkout to upgrade a company on an earlier plan (usage-pricing companies have no plan to upgrade)";
+        readonly description: "Open the switch to usage pricing for a company on an earlier plan (usage-pricing companies have nothing to change)";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;
@@ -8492,11 +8492,11 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly hidden: false;
         }, {
             readonly flags: "--no-browser";
-            readonly description: "Print the Stripe Checkout URL instead of opening it";
+            readonly description: "Print the URL instead of opening it";
             readonly hidden: false;
         }, {
             readonly flags: "--json";
-            readonly description: "Emit the Checkout URL as JSON";
+            readonly description: "Emit the URL as JSON";
             readonly hidden: false;
         }];
         readonly subcommands: readonly [];

package/dist/command-catalog.generated.js

@@ -1674,7 +1674,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "flags": "--company <slug>",
-                "description": "Also report this company's workspace plan state (Starter nag)",
+                "description": "Also report this company's billing and usage notice",
                 "hidden": false
             }
         ],
@@ -10339,7 +10339,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "upgrade",
-                "description": "Open Stripe Checkout to upgrade a company on an earlier plan (usage-pricing companies have no plan to upgrade)",
+                "description": "Open the switch to usage pricing for a company on an earlier plan (usage-pricing companies have nothing to change)",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -10355,12 +10355,12 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--no-browser",
-                        "description": "Print the Stripe Checkout URL instead of opening it",
+                        "description": "Print the URL instead of opening it",
                         "hidden": false
                     },
                     {
                         "flags": "--json",
-                        "description": "Emit the Checkout URL as JSON",
+                        "description": "Emit the URL as JSON",
                         "hidden": false
                     }
                 ],

package/dist/commands/access.d.ts

@@ -15,6 +15,7 @@
  */
 import { Command } from "commander";
 import { type CompanyBrowseClientFactory, type FilesBrowseVaultClient, type RunGetResult } from "./files-browse.js";
+import { type AclLock } from "./acl-lock.js";
 export type AccessOutcome = "never-existed" | "local" | "not-synced" | "no-access" | "ambiguous" | "pending-confirmation";
 export interface AccessAclTree {
     prefix: string;
@@ -145,6 +146,11 @@ export interface RunAccessResult {
     requestSentAt?: string;
     alreadyAskedAt?: string;
     requestNote?: string;
+    /**
+     * Most-specific ACL row covering the path when it has no grants. Broader
+     * grants (including a root `*` company-wide grant) do not apply.
+     */
+    lockedBy?: AclLock;
 }
 export interface AccessAsResult {
     personUid: string;

package/dist/commands/access.js

@@ -23,6 +23,7 @@ import { getCompanyUid, vaultApiFetch, resolveCallerUid } from "../utils/vault-a
 import { parseCompanySlugFromPath, classifyAclSource, resolveBrowseSession, makeCompanyPresignFactory, runGet, toBucketRelative, } from "./files-browse.js";
 import { listJournals, syncDoctor, } from "@indigoai-us/hq-cloud";
 import { listActiveMembers } from "./members.js";
+import { aclLockedBy } from "./acl-lock.js";
 import { buildDmBody } from "./dm.js";
 import { peekIdToken } from "../utils/id-token.js";
 import { findRecentAccessRequest, formatTimeAgo, recordAccessRequest, } from "../utils/access-requests.js";
@@ -458,10 +459,23 @@ async function completeTarget(input, deps, located) {
     const { resolvedKey, directory, vendDenied, listDenied, verdict, steps } = located;
     const resolvedPath = `companies/${slug}/${resolvedKey}`;
     let noAccess = vendDenied || listDenied;
+    // Name the empty fencing row only when the tree denies access. A role
+    // bypass or creator grant still reads the same as the acl/resolve fast
+    // path, which never fetches the tree.
+    const lockRow = verdict.kind === "tree" && aclDenied(verdict.tree) ? aclLockedBy(verdict.tree) : null;
+    const lockedBy = lockRow
+        ? { ...lockRow, path: `companies/${slug}/${toBucketRelative(lockRow.path, slug)}` }
+        : undefined;
+    if (lockedBy) {
+        steps.push(lockedBy.readUnknown
+            ? `acl: locked by ${lockedBy.path} unless that row is open (it has no grants; broader grants such as * apply only if it is open)`
+            : `acl: locked by ${lockedBy.path} (that row has no grants and is not open; broader grants such as * do not apply)`);
+    }
     if (verdict.kind === "resolved") {
         steps.push(`acl: ${verdict.permission}`);
     }
-    else if (verdict.tree == null || treeIsEmpty(verdict.tree)) {
+    else if (verdict.tree == null ||
+        (treeIsEmpty(verdict.tree) && !verdict.tree.coveringAclPath)) {
         steps.push("acl: no record (membership-distributed)");
     }
     else if (aclDenied(verdict.tree)) {
@@ -687,6 +701,7 @@ async function completeTarget(input, deps, located) {
         ...(requestSentAt ? { requestSentAt } : {}),
         ...(alreadyAskedAt ? { alreadyAskedAt } : {}),
         ...(requestNote ? { requestNote } : {}),
+        ...(lockedBy ? { lockedBy } : {}),
     }, finishCtx);
     return result;
 }
@@ -834,6 +849,8 @@ function jsonPayload(result) {
         payload.requestSentAt = result.requestSentAt;
     if (result.alreadyAskedAt)
         payload.alreadyAskedAt = result.alreadyAskedAt;
+    if (result.lockedBy)
+        payload.lockedBy = result.lockedBy;
     return payload;
 }
 function emit(input, result, log) {

package/dist/commands/acl-lock.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Empty-row lock detection for ACL tree responses (feedback dd287b55).
+ *
+ * The server resolves a path against its most-specific matching FILE_ACL row
+ * (`coveringAclPath` on the ACL tree response). Enforcement (files-presign,
+ * files-list, content) runs resolveEffectivePermission in hq-pro-core
+ * src/tenant-contracts/acl-permission.ts with `unionGrants: true`: grants on
+ * every matching row are unioned, except that an EMPTY, NON-OPEN winning row
+ * fences the path and grants nothing (only the row's creator and the
+ * owner/admin role bypass keep access). An OPEN empty winning row is not a
+ * fence: it floors every member at read and broader grants still apply.
+ */
+export interface AclLockTree {
+    prefix: string;
+    direct: unknown[];
+    inherited: Array<{
+        sourcePrefix: string;
+    }>;
+    directRow: {
+        open: boolean;
+    } | null;
+    coveringAclPath?: string | null;
+}
+export interface AclLock {
+    /** Path of the empty most-specific row. */
+    path: string;
+    /**
+     * True when the row's `open` flag is unknown. The tree reports `open` only
+     * for the exact prefix row (directRow), not for ancestor rows. Such a row is
+     * a lock if it is not open; if it is open, broader grants still apply.
+     */
+    readUnknown: boolean;
+}
+/**
+ * The empty, non-open row that fences `tree.prefix`, or null when the
+ * most-specific row grants something, is open, or no row covers the path.
+ */
+export declare function aclLockedBy(tree: AclLockTree | null | undefined): AclLock | null;
+/** One-line description of the lock for human output. */
+export declare function describeAclLock(lock: AclLock, display: string): string;
+//# sourceMappingURL=acl-lock.d.ts.map

package/dist/commands/acl-lock.js

@@ -0,0 +1,28 @@
+/**
+ * The empty, non-open row that fences `tree.prefix`, or null when the
+ * most-specific row grants something, is open, or no row covers the path.
+ */
+export function aclLockedBy(tree) {
+    const covering = tree?.coveringAclPath;
+    if (!tree || typeof covering !== "string" || covering === "")
+        return null;
+    if (covering === tree.prefix) {
+        if (!tree.directRow || tree.directRow.open === true)
+            return null;
+        if (!Array.isArray(tree.direct) || tree.direct.length > 0)
+            return null;
+        return { path: covering, readUnknown: false };
+    }
+    const inherited = Array.isArray(tree.inherited) ? tree.inherited : [];
+    if (inherited.some((entry) => entry.sourcePrefix === covering))
+        return null;
+    return { path: covering, readUnknown: true };
+}
+/** One-line description of the lock for human output. */
+export function describeAclLock(lock, display) {
+    if (lock.readUnknown) {
+        return `Locked by ${display} unless that row is open: it has no grants, so grants on broader prefixes apply only if it is open.`;
+    }
+    return `Locked by ${display}: that ACL row has no grants and is not open, so grants on broader prefixes do not apply. Only the row's creator and the owner/admin role bypass have access.`;
+}
+//# sourceMappingURL=acl-lock.js.map

package/dist/commands/agent-enroll.d.ts

@@ -60,6 +60,8 @@ export declare function mapEnrollFailure(status: number, body: {
     attemptsRemaining?: unknown;
     upgradeUrl?: unknown;
     pricingPlan?: unknown;
+    usagePause?: unknown;
+    billingState?: unknown;
 }, headers?: {
     retryAfter?: string | null;
 }): EnrollError;

package/dist/commands/agent-enroll.js

@@ -21,7 +21,7 @@ import * as path from "node:path";
 import { CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL, personTokenCacheFile, } from "../utils/cognito-session.js";
 import { HQ_CLIENT_NAME } from "../utils/vault-api.js";
-import { isUsageOnly, pricingPlanFromBody, usageOnlyCardRequiredLines, } from "../lib/billing/usage-only.js";
+import { isUsageOnly, pricingPlanFromBody, usageOnlyCardRequiredLines, usagePauseFromBody, } from "../lib/billing/usage-only.js";
 import { queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
 import { networkTransportErrorCode } from "../utils/network-transport-error.js";
 import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, planGateErrorFromPayload, } from "../utils/plan-gate-error.js";
@@ -139,6 +139,11 @@ export function mapEnrollFailure(status, body, headers) {
         return new EnrollError(`This agent was revoked; its enrollment code no longer works. An admin must ` +
             `create a new external agent or rotate this one.${suffix}`, status, code);
     }
+    // US-024: a usage pause is the server's own answer: its message and link.
+    const usagePause = status === 402 ? usagePauseFromBody(body) : null;
+    if (usagePause) {
+        return new EnrollError(usagePause.message, status, code, usagePause.actionUrl);
+    }
     if ((status === 402 || code === "billing_required") &&
         isUsageOnly(pricingPlanFromBody(body))) {
         // Usage pricing (US-012): no paid plan to upgrade to. A company admin adds
@@ -146,8 +151,8 @@ export function mapEnrollFailure(status, body, headers) {
         return new EnrollError(usageOnlyCardRequiredLines("An external agent").join(" ") + suffix, status, code);
     }
     if (status === 402 || code === "billing_required") {
-        return new EnrollError(`External agents are available on paid HQ plans only. A company admin must ` +
-            `upgrade the plan (\`hq billing\` or the console billing page) before enrolling.${suffix}`, status, code, typeof body.upgradeUrl === "string" ? body.upgradeUrl : undefined);
+        return new EnrollError(`External agents need billing set up for this company. A company admin can ` +
+            `add a card with \`hq billing checkout\` or on the console Billing page, then enroll again.${suffix}`, status, code, typeof body.upgradeUrl === "string" ? body.upgradeUrl : undefined);
     }
     if (status === 429 || code === "rate_limited") {
         const retryAfter = headers?.retryAfter?.trim();
@@ -425,7 +430,7 @@ export function registerAgentEnrollCommand(agent) {
                     }
                     catch (openErr) {
                         const message = openErr instanceof Error ? openErr.message : String(openErr);
-                        console.error(chalk.dim(`Could not open the upgrade link automatically: ${message}`));
+                        console.error(chalk.dim(`Could not open the billing link automatically: ${message}`));
                     }
                 }
             }

package/dist/commands/agents.js

@@ -131,12 +131,6 @@ export function agentCreatePlanLimitFromPayload(status, body) {
             : {}),
     };
 }
-function formatServerPrice(amountMinor, currency) {
-    return new Intl.NumberFormat("en-US", {
-        style: "currency",
-        currency,
-    }).format(amountMinor / 100);
-}
 async function offerAgentCheckout(url) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
     try {
@@ -146,7 +140,7 @@ async function offerAgentCheckout(url) {
         });
     }
     catch {
-        console.error("Could not open the upgrade page automatically. Use the URL above.");
+        console.error("Could not open the billing page automatically. Use the URL above.");
         return false;
     }
     finally {
@@ -156,7 +150,7 @@ async function offerAgentCheckout(url) {
 /** Print a server-priced plan block without minting or rewriting its URL. */
 export async function surfaceAgentCreatePlanLimit(planLimit, opts = {}) {
     if (isUsageOnly(opts.pricingPlan)) {
-        // Usage pricing (US-012): no Workforce plan to buy. The company adds a
+        // Usage pricing (US-012): no flat plan to buy. The company adds a
         // card and each agent box bills by size from the usage card.
         const card = opts.usageCard ?? BUNDLED_USAGE_CARD;
         for (const line of usageOnlyCardRequiredLines("An agent box", card)) {
@@ -166,13 +160,13 @@ export async function surfaceAgentCreatePlanLimit(planLimit, opts = {}) {
         queueCliLimitNoticeExposure("agents", "refusal", opts.companyUid);
         return;
     }
-    const price = `${formatServerPrice(planLimit.amountMinor, planLimit.currency)}/month`;
-    const reason = `HQ Workforce plan required to create an agent (${price}).`;
+    // The server's price was the flat plan's, which is closed: name no plan or price.
+    const reason = "Agents are not included on this company's current billing.";
     const argv = opts.json ? [...process.argv, "--json"] : process.argv;
     const interactive = canOfferTeamUpgrade(argv);
     if (!planLimit.checkoutUrl) {
         console.error(reason);
-        console.error("Ask a company owner to upgrade before creating an agent.");
+        console.error("Ask a company owner to check the company's Billing page before creating an agent.");
         queueCliLimitNoticeExposure("agents", "refusal", opts.companyUid);
         return;
     }

package/dist/commands/billing-sponsor.d.ts

@@ -2,9 +2,9 @@
  * `hq billing sponsor` — the individual-pull half of plan sponsorship, from the
  * terminal ("ask a company to sponsor me", hq-pro #3609).
  *
- * A person who is over a personal limit has exactly three ways out: pay $50
- * themselves, reduce what they store, or ask a company to cover the $50 plan
- * line. This command is the third one, plus the admin side that answers it.
+ * A person who is over a personal limit has exactly three ways out: pay for
+ * the personal plan themselves, reduce what they store, or ask a company to
+ * cover it. This command is the third one, plus the admin side that answers it.
  *
  *   hq billing sponsor request <company>   — ask that company to cover my plan
  *   hq billing sponsor list                — the queue (admins), or my own
@@ -36,7 +36,7 @@ export declare const PLAN_RESOURCE: "plan";
 /** What a person is told when hq-pro's plan-sponsorship switch is off. */
 export declare const FEATURE_OFF_MESSAGE = "Asking a company to sponsor your plan isn't available yet.";
 /** What v1 sponsorship covers, stated wherever a person confirms or reads it. */
-export declare const COVERAGE_SENTENCE = "Your company pays your $50 plan. Storage above your plan's allowance is still yours.";
+export declare const COVERAGE_SENTENCE = "Your company pays your personal plan. Storage above your plan's allowance is still yours.";
 /** What a person is told while an approval waits on the sponsor's card. */
 export declare const HELD_FOR_CARD_SENTENCE = "Your company said yes and is adding a card. Your limits still apply until then.";
 /** One request row as hq-pro persists and returns it. */

package/dist/commands/billing-sponsor.js

@@ -2,9 +2,9 @@
  * `hq billing sponsor` — the individual-pull half of plan sponsorship, from the
  * terminal ("ask a company to sponsor me", hq-pro #3609).
  *
- * A person who is over a personal limit has exactly three ways out: pay $50
- * themselves, reduce what they store, or ask a company to cover the $50 plan
- * line. This command is the third one, plus the admin side that answers it.
+ * A person who is over a personal limit has exactly three ways out: pay for
+ * the personal plan themselves, reduce what they store, or ask a company to
+ * cover it. This command is the third one, plus the admin side that answers it.
  *
  *   hq billing sponsor request <company>   — ask that company to cover my plan
  *   hq billing sponsor list                — the queue (admins), or my own
@@ -41,7 +41,7 @@ export const PLAN_RESOURCE = "plan";
 /** What a person is told when hq-pro's plan-sponsorship switch is off. */
 export const FEATURE_OFF_MESSAGE = "Asking a company to sponsor your plan isn't available yet.";
 /** What v1 sponsorship covers, stated wherever a person confirms or reads it. */
-export const COVERAGE_SENTENCE = "Your company pays your $50 plan. Storage above your plan's allowance is still yours.";
+export const COVERAGE_SENTENCE = "Your company pays your personal plan. Storage above your plan's allowance is still yours.";
 /** What a person is told while an approval waits on the sponsor's card. */
 export const HELD_FOR_CARD_SENTENCE = "Your company said yes and is adding a card. Your limits still apply until then.";
 /**
@@ -85,7 +85,7 @@ export function messageForError(status, body) {
     if (status === 401)
         return "Your sign-in has expired. Run `hq login` and try again.";
     if (status === 403 && code === "SPONSOR_PLAN_REQUIRED") {
-        return "That company's plan can't cover an individual plan. Only HQ Workforce and Enterprise companies can.";
+        return "That company can't cover a personal plan on its current billing. Ask an owner of that company to check its Billing page.";
     }
     if (status === 403) {
         return "You're not allowed to do that. Only an owner or admin of the company can answer a sponsorship request.";
@@ -209,7 +209,7 @@ export function registerBillingSponsorCommands(billing) {
                 process.stdout.write(JSON.stringify(data.request, null, 2) + "\n");
                 return;
             }
-            console.log(`Asked ${company} to cover your $50 HQ plan.`);
+            console.log(`Asked ${company} to cover your personal HQ plan.`);
             console.log(COVERAGE_SENTENCE);
             console.log(`An owner or admin there answers next. Check with \`hq billing sponsor list\`.`);
         }
@@ -276,11 +276,11 @@ export function registerBillingSponsorCommands(billing) {
                 }
                 const where = named ?? "that company";
                 if (!state.active) {
-                    console.log(`No company is covering your $50 HQ plan right now.`);
+                    console.log(`No company is covering your personal HQ plan right now.`);
                     console.log(`If you asked ${where}, they haven't answered yet — an owner or admin there answers next.`);
                     return;
                 }
-                console.log(`Your $50 HQ plan: ${statusLabel(state.status ?? "active")}`);
+                console.log(`Your personal HQ plan: ${statusLabel(state.status ?? "active")}`);
                 if (state.requestId)
                     console.log(`  ${chalk.bold(state.requestId)}`);
                 console.log(COVERAGE_SENTENCE);
@@ -328,7 +328,7 @@ export function registerBillingSponsorCommands(billing) {
             }
             console.log((await companyIsUsageOnly(result.companyUid))
                 ? "Approved. Their personal plan is now on the company bill."
-                : "Approved. Their $50 plan is now on the company bill.");
+                : "Approved. Their personal plan is now on the company bill.");
         }
         catch (err) {
             fail(err);
@@ -370,7 +370,7 @@ export function registerBillingSponsorCommands(billing) {
             }
             console.log((await companyIsUsageOnly(result.companyUid))
                 ? "Ended. Their personal plan goes back to them from the next bill."
-                : "Ended. Their $50 plan goes back to them from the next bill.");
+                : "Ended. Their personal plan goes back to them from the next bill.");
         }
         catch (err) {
             fail(err);
@@ -396,7 +396,7 @@ export function registerBillingSponsorCommands(billing) {
                 console.log(usageOnlySponsorLines()[2]);
                 return;
             }
-            console.log("Withdrawn. You can pay the $50 yourself, reduce what you store, or ask another company.");
+            console.log("Withdrawn. You can pay for your plan yourself, reduce what you store, or ask another company.");
         }
         catch (err) {
             fail(err);

package/dist/commands/billing-usage.d.ts

@@ -12,18 +12,18 @@
  *
  * Tenant boundary: the company comes from the caller's own active memberships
  * (`/membership/me`); a slug outside them is refused before any read. The
- * usage-limits routes are member-gated on the server as well. With no cloud
+ * company statement is owner-gated on the server as well. With no cloud
  * company (or `--personal`) it reads the caller's personal scope.
  *
- * Usage numbers come through `readMonthUsage` (src/lib/billing/usage-cost.ts),
- * the single seam to switch to the US-005 daily rollup once it has a read route.
+ * Usage numbers come through `readMonthUsage` (src/lib/billing/usage-cost.ts)
+ * from the usage statement, `GET /v1/billing/usage` (hq-pro US-006). Only a
+ * server without that route (404) falls back to the usage-limits readings.
  *
  * Only an account on usage pricing gets costs. The plan comes from the
- * server: `pricingPlan` / `usageOnly` on the usage-limits body (hq-pro #5042,
- * computed with `isOnUsagePricing`). Only when that body does not say, the
- * billing summary the command already reads for the trial. A flat-plan account (for example a Workforce
- * company that subscribed before the 2026-10-16 cutover) and an account the
- * server says nothing about get readings only, with no rate, cost or
+ * server's shared plan status (`billingState`, hq-pro #5088) on the billing
+ * summary, with the legacy `pricingPlan` / `usageOnly` fields for a server
+ * that does not send it. An account on an earlier flat plan and an account
+ * the server says nothing about get readings only, with no rate, cost or
  * projected bill.
  */
 import type { Command } from "commander";
@@ -34,8 +34,19 @@ export interface MembershipRef {
     slug: string;
     role?: string;
 }
+/** One `GET /v1/billing/usage` answer: the HTTP status and the decoded body. */
+export interface UsageStatementResponse {
+    status: number;
+    body: unknown | null;
+}
 export interface BillingUsageDeps {
     listCompanies(): Promise<MembershipRef[]>;
+    /**
+     * `GET /v1/billing/usage` for the scope (US-015). Absent, or a 404 from a
+     * server without the route, falls back to {@link fetchUsageLimits}.
+     */
+    fetchUsageStatement?: (scope: UsageScope) => Promise<UsageStatementResponse>;
+    /** Legacy readings for a server without the statement route. */
     fetchUsageLimits: ReadMonthUsageDeps["fetchUsageLimits"];
     readStorageSplit?: (company: MembershipRef, opts: {
         fresh: boolean;
@@ -77,6 +88,9 @@ export declare function pricingPlanFromSummary(body: unknown): PricingPlan | nul
  * only when usage-limits does not say.
  */
 export declare function resolveOnUsagePricing(limitsPlan: PricingPlan | null, summaryPlan: PricingPlan | null): boolean | null;
+/** Thrown when the company statement is refused to a caller who is not its owner. */
+export declare class UsageStatementForbiddenError extends Error {
+}
 export declare function runBillingUsage(opts: BillingUsageOptions, deps: BillingUsageDeps): Promise<BillingUsageReport>;
 /**
  * `hq billing usage --card`: the card from GET /v1/pricing, or the bundled

package/dist/commands/billing-usage.js

@@ -12,27 +12,27 @@
  *
  * Tenant boundary: the company comes from the caller's own active memberships
  * (`/membership/me`); a slug outside them is refused before any read. The
- * usage-limits routes are member-gated on the server as well. With no cloud
+ * company statement is owner-gated on the server as well. With no cloud
  * company (or `--personal`) it reads the caller's personal scope.
  *
- * Usage numbers come through `readMonthUsage` (src/lib/billing/usage-cost.ts),
- * the single seam to switch to the US-005 daily rollup once it has a read route.
+ * Usage numbers come through `readMonthUsage` (src/lib/billing/usage-cost.ts)
+ * from the usage statement, `GET /v1/billing/usage` (hq-pro US-006). Only a
+ * server without that route (404) falls back to the usage-limits readings.
  *
  * Only an account on usage pricing gets costs. The plan comes from the
- * server: `pricingPlan` / `usageOnly` on the usage-limits body (hq-pro #5042,
- * computed with `isOnUsagePricing`). Only when that body does not say, the
- * billing summary the command already reads for the trial. A flat-plan account (for example a Workforce
- * company that subscribed before the 2026-10-16 cutover) and an account the
- * server says nothing about get readings only, with no rate, cost or
+ * server's shared plan status (`billingState`, hq-pro #5088) on the billing
+ * summary, with the legacy `pricingPlan` / `usageOnly` fields for a server
+ * that does not send it. An account on an earlier flat plan and an account
+ * the server says nothing about get readings only, with no rate, cost or
  * projected bill.
  */
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, vaultApiFetchPublic } from "../utils/vault-api.js";
-import { buildReadingsReport, buildReport, formatReport, readMonthUsage, } from "../lib/billing/usage-cost.js";
+import { buildReadingsReport, buildReport, formatReport, readMonthUsage, usageLimitsSource, usageStatementSource, } from "../lib/billing/usage-cost.js";
 import { ratesFromPricingStatement } from "../lib/billing/usage-rate-card.js";
 import { fetchUsageCard, formatUsageCardLines } from "../lib/billing/usage-card.js";
-import { fetchCompanyBillingSummary, pricingPlanFromBody, usageTrialActiveFromBody, } from "../lib/billing/usage-only.js";
+import { fetchCompanyBillingSummary, pricingPlanFromBody, hasBillingStateField, usageTrialActiveFromBody, } from "../lib/billing/usage-only.js";
 export class UsageScopeError extends Error {
 }
 /** Pick the scope. Never reaches outside the caller's own memberships. */
@@ -67,7 +67,7 @@ function asRecord(value) {
 /** The plan on a usage-limits body: `pricingPlan`, else the `usageOnly` / `onUsagePricing` boolean. */
 export function pricingPlanFromUsageLimits(body) {
     const plan = pricingPlanFromBody(body);
-    if (plan)
+    if (plan || hasBillingStateField(body))
         return plan;
     const rec = asRecord(body);
     const flag = typeof rec?.onUsagePricing === "boolean" ? rec.onUsagePricing : rec?.usageOnly;
@@ -85,9 +85,12 @@ export function pricingPlanFromSummary(body) {
     const rec = asRecord(body);
     if (!rec)
         return null;
-    // `plan: "usage"` only means "no Workforce subscription", not usage pricing,
-    // so it never turns pricing on. Without pricingPlan, show no cost.
-    return pricingPlanFromBody(rec) ?? "current";
+    // `plan: "usage"` only means "no flat-plan subscription", not usage pricing,
+    // so it never turns pricing on. A server that sends billingState answers
+    // from it alone (unknown stays unknown); an older one without pricingPlan
+    // shows no cost.
+    const plan = pricingPlanFromBody(rec);
+    return hasBillingStateField(rec) ? plan : plan ?? "current";
 }
 /**
  * True: price the meters. False: flat plan. Null: unknown, show no cost.
@@ -101,20 +104,44 @@ export function resolveOnUsagePricing(limitsPlan, summaryPlan) {
         return null;
     return plan === "usage-only";
 }
+/** Thrown when the company statement is refused to a caller who is not its owner. */
+export class UsageStatementForbiddenError extends Error {
+}
+/**
+ * Read the statement, or say the caller should use the legacy readings: null
+ * means the server has no statement route (404) or no reader was given.
+ */
+async function readStatementBody(scope, deps) {
+    if (!deps.fetchUsageStatement)
+        return null;
+    const res = await deps.fetchUsageStatement(scope);
+    if (res.status === 404)
+        return null;
+    if (res.status === 403 && scope.kind === "company") {
+        throw new UsageStatementForbiddenError(`Only the owner of '${scope.companySlug}' can see its usage statement. ` +
+            "Run `hq billing usage --personal` for your own usage.");
+    }
+    return { body: res.status >= 200 && res.status < 300 ? res.body : null };
+}
 export async function runBillingUsage(opts, deps) {
     const memberships = await deps.listCompanies();
     const scope = resolveUsageScope(memberships, opts);
     const membership = scope.kind === "company" ? memberships.find((m) => m.uid === scope.companyUid) : undefined;
     let limitsBody = null;
+    const statement = await readStatementBody(scope, deps);
+    const usageDeps = {
+        fetchUsageLimits: async (s) => (limitsBody = await deps.fetchUsageLimits(s)),
+        now: deps.now,
+        ...(deps.readTrialActive ? { readTrialActive: deps.readTrialActive } : {}),
+        ...(opts.storageScan !== false && deps.readStorageSplit && membership
+            ? { readStorageSplit: () => deps.readStorageSplit(membership, { fresh: opts.fresh === true }) }
+            : {}),
+    };
+    const source = statement
+        ? usageStatementSource(async () => statement.body)
+        : usageLimitsSource(usageDeps);
     const [usage, pricing] = await Promise.all([
-        readMonthUsage(scope, {
-            fetchUsageLimits: async (s) => (limitsBody = await deps.fetchUsageLimits(s)),
-            now: deps.now,
-            ...(deps.readTrialActive ? { readTrialActive: deps.readTrialActive } : {}),
-            ...(opts.storageScan !== false && deps.readStorageSplit && membership
-                ? { readStorageSplit: () => deps.readStorageSplit(membership, { fresh: opts.fresh === true }) }
-                : {}),
-        }),
+        readMonthUsage(scope, usageDeps, source),
         deps.fetchPricing().catch(() => null),
     ]);
     const limitsPlan = pricingPlanFromUsageLimits(limitsBody);
@@ -142,6 +169,14 @@ function productionDeps() {
             const { companiesFromMemberships } = await import("./storage.js");
             return companiesFromMemberships(await res.json());
         },
+        async fetchUsageStatement(scope) {
+            const res = await vaultApiFetch(scope.kind === "company"
+                ? { token: await token(), path: "/v1/billing/usage", query: { companyUid: scope.companyUid } }
+                : { token: await token(), path: "/v1/billing/usage", query: { scope: "person" } });
+            if (!res.ok)
+                return { status: res.status, body: null };
+            return { status: res.status, body: await res.json().catch(() => null) };
+        },
         async fetchUsageLimits(scope) {
             const res = await vaultApiFetch(scope.kind === "company"
                 ? { token: await token(), path: "/v1/billing/usage-limits", query: { companyUid: scope.companyUid } }