@indigoai-us/hq-cli 5.345.163 → 5.345.165

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## [Unreleased]
 
+## [5.345.165] — 2026-10-23
+- `hq billing sponsor grant <email|prs_id> --company <slug>` lets a company owner or admin put a member's personal plan on the company bill without a request first; `--all-members` does it for every active member and reports each person as covered, already covered, or skipped. `hq billing sponsor ungrant <email|prs_id>` takes it off again. hq-pro checks the owner/admin role and active membership.
+- `hq scan secrets <files...>` takes `--repo <dir>`, which applies that repo's committed `.gitleaks.toml` allowlists to a file scan, matching each file by its path relative to the repo, as a staged scan does. `--snapshot-root <dir>` (with `--repo`) matches files laid out as `<dir>/<commit>/<repo path>`, the history copies `commit-secret-scan.sh pr-check` writes, as `<repo path>`. Findings still name the files as given. Before this, a file scan ignored the repo's allowlists, so pr-check failed on false positives the commit gate already allowed. Without `--repo` a file scan is unchanged.
+- `--allowlist-rev <rev>` (with `--repo`) reads `.gitleaks.toml` from that commit instead of HEAD; pr-check passes its base branch, so a branch cannot exempt its own earlier commits by adding an allowlist later. An unknown rev exits 2.
+- A file that resolves (after `..` and symlinks) outside the repo and the snapshot root gets no repo allowlist, nor does a snapshot file without a commit folder.
+- A file scan with `--repo` honors only exact-value exemptions. Each allowlist needs `condition = "AND"` and specific `paths`, and lists in `stopwords` the exact secret values it allows, such as known manifest digests (at least 16 characters, no spaces). A detected secret is allowed only when it equals one of them, so other secrets in the same file are still reported. An allowlist with `regexes`, `regexTarget`, `targetRules` or `commits`, or with paths alone, is refused and the scan exits 2, because patterns, alone or combined across entries, can hide a real credential. Staged scans keep the full allowlist format; there each allowlist with content checks is judged by running the real detector on a fixed set of realistic credentials and refused if it hides any of them.
+- An allowlist validation error never prints an exemption value. It names the entry and position (for example `stopwords[0]`) with the value's length and a short SHA-256 prefix, so a credential typed into an allowlist by mistake does not reach terminal or CI logs.
+
+## [5.345.164] — 2026-10-23
+- `hq billing status` and `hq billing usage --card` now show trial usage against the $500 trial cap, the $10 included usage, the spend limit and a prompt to add a card when usage passes the included amount. The plan line says "unavailable right now" instead of guessing Starter, invoice-billed companies read as a flat plan billed by invoice, and a failed read of a scheduled switch is reported.
+- `hq deploy domains` refuses a name that is really an IPv4 address. Inputs such as `1.2`, `0x7f.1` and `1.2.3.4` were rewritten to an address and accepted; a numeric last label is now refused before any request.
+- `hq deploy domains buy`: when the domain is registered but the card charge does not complete, the output now prints the order's idempotency key and says to run the same command again with it to retry the charge. It no longer says that HQ billing follows up, which nothing did.
+- `--company` that matches the folder's link in a different case is accepted, and the link's slug is sent.
+- `hq doctor` now says which cloud call the sync receiver was refused on. `sync.runtime.receiver-permission` breaks its count down by call class (the per-device queue credentials from `POST /v1/sync/subscribe`, the subscribe call itself, the latency metric, or the object pull after a change event) and gives the matching next step, instead of one bare count. A new `sync.runtime.pull-access-denied` check warns when the same vault key was refused on two or more pulls in the hour and names the repeatedly refused keys (relative keys only, at most 10, with the runner's latest reason tag; a key refused once is counted but not named). In a session locked to companies, only keys from those companies are named and the rest are counted, so doctor never prints another company's file names from the machine-wide sync log; a refusal with no company label is shown as `unknown` with no lookup command. The warning gives the `hq files acl` command to compare the stored grant with the key the pull looked up. Before this, every automated client-health report for a refused receiver carried only a count and could not be acted on (feedback_cd56a501 and 27 linked reports).
+- A stale sync journal whose `hq doctor --fix` pull ended offline, timed out, or hit a server 5xx is no longer reported as unrepaired by the client-health hook: doctor JSON leaves those rows out for 15 minutes after the attempt and lists them under `transientRefreshSyncCheckIds`, so the next SessionStart retries the pull instead of filing a report. A pull the service refused (4xx) or that failed for another reason is still reported. The `--fix` progress file records each journal's pull outcome as additive fields (still version 2, so an older CLI sharing the same HQ root keeps reading it, and an outcome value this CLI does not know is dropped rather than failing `--fix`); a journal that has failed transiently for more than 24 hours is reported again.
+- `hq-hook bridge-plan` now also lists bridged helpers: `derive-trigger-facts`
+  appears when its flag `hook-engine-port-derive-trigger-facts` is `shadow` or
+  `on`. master-hook.sh passes the plan to the policy injector, which then runs
+  its fact helper through `hq-hook bridge derive-trigger-facts` instead of
+  bash (US-008). The flag defaults to off, the kill switch still forces bash,
+  and `hq-hook --self-check` reports the list as `helper_bridge_ports`. The
+  engine version is now 0.3.0.
+- `hq-hook run policy-enforcement-gate` is the first hook port master-hook.sh
+  can bridge (US-022, flag `hook-engine-port-policy-enforcement-gate`, default
+  off). It answers the gate's allow paths without starting a process: no
+  session id, no session state, a PostToolUse with no state, an event the gate
+  does not handle, and a PreToolUse that is not outbound, matches no gate
+  policy and has no requirement to merge. For a Bash PreToolUse it writes the
+  same pre-tool pass stamp the bash gate writes. Every other case (outbound
+  tools and commands, gate policies, requirement merges, receipts,
+  UserPromptSubmit, non-ASCII input, jq not found on PATH, anything it cannot
+  parse) exits 75, and
+  the bridge runs the bash gate. The port never blocks.
+- HQ Sync now reacts to secure real-time wake notifications on macOS, so shared
+  vault changes can start syncing within seconds without frequent polling.
+
 ## [5.345.163] — 2026-10-23
 - New `hq deploy domains` manages custom domains on a deployed app from the installed CLI, using the same hq-deploy routes as the desktop Deployments panel. `list`, `add <domain>`, `refresh <domain>` and `remove <domain>` take `--app <name or id>`, or use the app linked to the folder (`.hq/project.json`, or the older `hq-deploy.json`; `--path` picks the folder). Domains are checked before any request: hostname labels only (no URL, path, port or `@`), and an internationalized name is sent as punycode. A folder link that names no company needs `--company`, and a `--company` that differs from the link is refused. `add` names the app and company, shows the add-on price from `GET /v1/pricing`, and asks for approval (or `--yes`) before anything is added, then prints the DNS records to create, the guidance for a bare domain, and the billing link when the company has no card. `refresh` exits 2 while the domain is not live, so scripts can poll. `remove` names the app and company, asks for approval (or `--yes`), and says when the billing removal is queued for retry. Member, entitlement and billing errors print plain messages, and every command takes `--json`.
 - New `hq deploy domains search <query>` and `hq deploy domains buy <domain> --price <usd> --registrant-file <path>` buy a domain for the company through hq-pro's domain purchase routes. `buy` names the company that pays and shows the first-year price and the published renewal and refund terms, and asks for approval (or `--yes`). It sends one idempotency key per order and only the documented registrant fields. Whenever the outcome is not known (a network error, a server error, a pending registration), it prints the key and says to re-run with `--idempotency-key` instead of starting a new order. Buying stays unavailable until the server has registrar credentials; until then the command says nothing was charged.

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

@@ -6277,6 +6277,18 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--json";
             readonly description: "Print findings as JSON";
             readonly hidden: false;
+        }, {
+            readonly flags: "--repo <dir>";
+            readonly description: "With files: apply this repo's committed .gitleaks.toml allowlists, matching repo-relative paths";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--snapshot-root <dir>";
+            readonly description: "With --repo: files under <dir>/<commit>/<path> are matched as <path>";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--allowlist-rev <rev>";
+            readonly description: "With --repo: read .gitleaks.toml from this commit instead of HEAD";
+            readonly hidden: false;
         }];
         readonly subcommands: readonly [];
     }];
@@ -8820,6 +8832,60 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly hidden: false;
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "grant";
+            readonly description: "Admin: put a member's personal plan on the company bill, no request needed";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly helpOption: true;
+            readonly helpCommand: false;
+            readonly usage: "[options] [person]";
+            readonly helpText: readonly [];
+            readonly arguments: readonly [{
+                readonly name: "person";
+                readonly required: false;
+                readonly variadic: false;
+                readonly description: "Member email or prs_ id";
+            }];
+            readonly options: readonly [{
+                readonly flags: "--company <slug>";
+                readonly description: "Company slug (resolves to companyUid)";
+                readonly hidden: false;
+            }, {
+                readonly flags: "--all-members";
+                readonly description: "Sponsor every active member of the company";
+                readonly hidden: false;
+            }, {
+                readonly flags: "--json";
+                readonly description: "Emit raw JSON";
+                readonly hidden: false;
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "ungrant";
+            readonly description: "Admin: take a member's personal plan off the company bill";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly helpOption: true;
+            readonly helpCommand: false;
+            readonly usage: "[options] <person>";
+            readonly helpText: readonly [];
+            readonly arguments: readonly [{
+                readonly name: "person";
+                readonly required: true;
+                readonly variadic: false;
+                readonly description: "Member email or prs_ id";
+            }];
+            readonly options: readonly [{
+                readonly flags: "--company <slug>";
+                readonly description: "Company slug (resolves to companyUid)";
+                readonly hidden: false;
+            }, {
+                readonly flags: "--json";
+                readonly description: "Emit raw JSON";
+                readonly hidden: false;
+            }];
+            readonly subcommands: readonly [];
         }];
     }, {
         readonly name: "usage";

package/dist/command-catalog.generated.js

@@ -7634,6 +7634,21 @@ export const COMMAND_CATALOG = [
                         "flags": "--json",
                         "description": "Print findings as JSON",
                         "hidden": false
+                    },
+                    {
+                        "flags": "--repo <dir>",
+                        "description": "With files: apply this repo's committed .gitleaks.toml allowlists, matching repo-relative paths",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--snapshot-root <dir>",
+                        "description": "With --repo: files under <dir>/<commit>/<path> are matched as <path>",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--allowlist-rev <rev>",
+                        "description": "With --repo: read .gitleaks.toml from this commit instead of HEAD",
+                        "hidden": false
                     }
                 ],
                 "subcommands": []
@@ -10757,6 +10772,73 @@ export const COMMAND_CATALOG = [
                             }
                         ],
                         "subcommands": []
+                    },
+                    {
+                        "name": "grant",
+                        "description": "Admin: put a member's personal plan on the company bill, no request needed",
+                        "aliases": [],
+                        "hidden": false,
+                        "helpOption": true,
+                        "helpCommand": false,
+                        "usage": "[options] [person]",
+                        "helpText": [],
+                        "arguments": [
+                            {
+                                "name": "person",
+                                "required": false,
+                                "variadic": false,
+                                "description": "Member email or prs_ id"
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Company slug (resolves to companyUid)",
+                                "hidden": false
+                            },
+                            {
+                                "flags": "--all-members",
+                                "description": "Sponsor every active member of the company",
+                                "hidden": false
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "Emit raw JSON",
+                                "hidden": false
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "ungrant",
+                        "description": "Admin: take a member's personal plan off the company bill",
+                        "aliases": [],
+                        "hidden": false,
+                        "helpOption": true,
+                        "helpCommand": false,
+                        "usage": "[options] <person>",
+                        "helpText": [],
+                        "arguments": [
+                            {
+                                "name": "person",
+                                "required": true,
+                                "variadic": false,
+                                "description": "Member email or prs_ id"
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Company slug (resolves to companyUid)",
+                                "hidden": false
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "Emit raw JSON",
+                                "hidden": false
+                            }
+                        ],
+                        "subcommands": []
                     }
                 ]
             },

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

@@ -13,6 +13,13 @@
  *   hq billing sponsor decline <id>        — admin: say no
  *   hq billing sponsor revoke  <id>        — admin: end an active sponsorship
  *   hq billing sponsor withdraw <id>       — me: take back my own request
+ *   hq billing sponsor grant <person> --company <slug>
+ *                                          — admin: sponsor a member's plan
+ *                                            directly, no request needed
+ *   hq billing sponsor grant --all-members --company <slug>
+ *                                          — admin: sponsor every active member
+ *   hq billing sponsor ungrant <person> --company <slug>
+ *                                          — admin: end a direct sponsorship
  *
  * Every subcommand talks to the SAME hq-pro routes the console uses
  * (`/v1/billing/sponsorship/...`). hq-pro is the authoritative gate on all of
@@ -82,6 +89,19 @@ export interface SponsorshipSelfState {
 }
 /** Plain label for a request status. Never shows the raw enum. */
 export declare function statusLabel(status: string): string;
+/** Per-person outcome of an owner/admin grant, as hq-pro returns it. */
+export interface PlanGrantResult {
+    personUid: string;
+    resourceId: string;
+    outcome: "sponsored" | "already_sponsored" | "sponsored_by_another_company" | "usage_pricing" | "not_a_member";
+}
+/** Plain line for one grant outcome. */
+export declare function grantOutcomeLabel(outcome: PlanGrantResult["outcome"]): string;
+/**
+ * Turn `<person>` into a person uid: a `prs_` uid passes through, an email is
+ * looked up in the company's active members. hq-pro re-checks membership.
+ */
+export declare function resolveMemberPersonUid(token: string, companyUid: string, person: string): Promise<string>;
 export declare function registerBillingSponsorCommands(billing: Command): void;
 export {};
 //# sourceMappingURL=billing-sponsor.d.ts.map

package/dist/commands/billing-sponsor.js

@@ -13,6 +13,13 @@
  *   hq billing sponsor decline <id>        — admin: say no
  *   hq billing sponsor revoke  <id>        — admin: end an active sponsorship
  *   hq billing sponsor withdraw <id>       — me: take back my own request
+ *   hq billing sponsor grant <person> --company <slug>
+ *                                          — admin: sponsor a member's plan
+ *                                            directly, no request needed
+ *   hq billing sponsor grant --all-members --company <slug>
+ *                                          — admin: sponsor every active member
+ *   hq billing sponsor ungrant <person> --company <slug>
+ *                                          — admin: end a direct sponsorship
  *
  * Every subcommand talks to the SAME hq-pro routes the console uses
  * (`/v1/billing/sponsorship/...`). hq-pro is the authoritative gate on all of
@@ -35,6 +42,7 @@ import { diagnosticsEnabled } from "../lib/diagnostics.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { isCompanySelectionError } from "../utils/company-selection-error.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { listActiveMembers } from "./members.js";
 import { fetchCompanyPricingPlan, fetchPersonPricingPlan, isUsageOnly, usageOnlySponsorLines, } from "../lib/billing/usage-only.js";
 /** The request kind this command files. Matches hq-pro's contract. */
 export const PLAN_RESOURCE = "plan";
@@ -90,6 +98,9 @@ export function messageForError(status, body) {
     if (status === 403) {
         return "You're not allowed to do that. Only an owner or admin of the company can answer a sponsorship request.";
     }
+    if (status === 404 && code === "NOT_A_MEMBER") {
+        return "That person isn't an active member of this company.";
+    }
     if (status === 404)
         return "No sponsorship request with that id.";
     if (status === 409 && code === "DUPLICATE_PENDING_REQUEST") {
@@ -168,6 +179,41 @@ async function transition(requestId, op) {
     });
     return { ...data.request, code: data.code, addCardUrl: data.addCardUrl };
 }
+/** Plain line for one grant outcome. */
+export function grantOutcomeLabel(outcome) {
+    switch (outcome) {
+        case "sponsored":
+            return "Now on the company bill";
+        case "already_sponsored":
+            return "Already on the company bill";
+        case "sponsored_by_another_company":
+            return "Skipped: another company already covers them";
+        case "usage_pricing":
+            return "Skipped: on usage pricing, no personal plan to cover";
+        case "not_a_member":
+            return "Skipped: not an active member";
+        default:
+            return outcome;
+    }
+}
+/**
+ * Turn `<person>` into a person uid: a `prs_` uid passes through, an email is
+ * looked up in the company's active members. hq-pro re-checks membership.
+ */
+export async function resolveMemberPersonUid(token, companyUid, person) {
+    const trimmed = person.trim();
+    if (/^prs_[A-Za-z0-9]+$/.test(trimmed))
+        return trimmed;
+    const email = trimmed.toLowerCase();
+    if (!/^[^\s]+@[^\s]+$/.test(email)) {
+        throw new SponsorError("Pass the person's email or their prs_ id.");
+    }
+    const members = await listActiveMembers(token, companyUid);
+    const match = members.find((m) => m.personEmail?.trim().toLowerCase() === email);
+    if (match?.personUid)
+        return match.personUid;
+    throw new SponsorError(`No active member has the email ${email}. Run \`hq members list\`.`);
+}
 /** Whether the sponsoring company is on usage pricing. Unknown counts as no. */
 async function companyIsUsageOnly(companyUid) {
     if (!companyUid)
@@ -402,5 +448,75 @@ export function registerBillingSponsorCommands(billing) {
             fail(err);
         }
     });
+    sponsor
+        .command("grant")
+        .argument("[person]", "Member email or prs_ id")
+        .description("Admin: put a member's personal plan on the company bill, no request needed")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--all-members", "Sponsor every active member of the company")
+        .option("--json", "Emit raw JSON")
+        .action(async function (person, opts) {
+        try {
+            if (Boolean(person) === Boolean(opts.allMembers)) {
+                throw new SponsorError("Name one person, or pass --all-members.");
+            }
+            const token = await ensureCognitoToken();
+            const named = opts.company ?? billing.opts().company;
+            const companyUid = await getCompanyUid(token, named);
+            const body = { companyUid };
+            if (person)
+                body.personUid = await resolveMemberPersonUid(token, companyUid, person);
+            else
+                body.allMembers = true;
+            const data = await callApi(token, "/v1/billing/sponsorship/plans", { method: "POST", body });
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+                return;
+            }
+            if (data.results.length === 0) {
+                console.log("No active members to sponsor.");
+                return;
+            }
+            for (const r of data.results) {
+                console.log(`  ${chalk.bold(r.personUid)}  ${grantOutcomeLabel(r.outcome)}`);
+            }
+            const added = data.results.filter((r) => r.outcome === "sponsored").length;
+            console.log(added === 1
+                ? "1 personal plan moved onto the company bill."
+                : `${added} personal plans moved onto the company bill.`);
+            const single = person ? data.results[0] : undefined;
+            if (single && single.outcome !== "sponsored" && single.outcome !== "already_sponsored") {
+                process.exitCode = 1;
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    sponsor
+        .command("ungrant")
+        .argument("<person>", "Member email or prs_ id")
+        .description("Admin: take a member's personal plan off the company bill")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--json", "Emit raw JSON")
+        .action(async function (person, opts) {
+        try {
+            const token = await ensureCognitoToken();
+            const named = opts.company ?? billing.opts().company;
+            const companyUid = await getCompanyUid(token, named);
+            const personUid = await resolveMemberPersonUid(token, companyUid, person);
+            const data = await callApi(token, "/v1/billing/sponsorship/plans", { method: "DELETE", body: { companyUid, personUid } });
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+                return;
+            }
+            console.log(data.revoked
+                ? "Ended. Their personal plan goes back to them from the next bill."
+                : "This company wasn't covering their plan. Nothing changed.");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
 }
 //# sourceMappingURL=billing-sponsor.js.map

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

@@ -28,7 +28,8 @@
  */
 import type { Command } from "commander";
 import { type BillingUsageReport, type ReadMonthUsageDeps, type StorageSplit, type UsageScope } from "../lib/billing/usage-cost.js";
-import { type PricingPlan } from "../lib/billing/usage-only.js";
+import { type UsageCard } from "../lib/billing/usage-card.js";
+import { type SharedBillingState, type PricingPlan } from "../lib/billing/usage-only.js";
 export interface MembershipRef {
     uid: string;
     slug: string;
@@ -60,6 +61,11 @@ export interface BillingUsageDeps {
      * for the plan when usage-limits does not carry it (older server).
      */
     fetchBillingSummary?: (scope: UsageScope) => Promise<unknown | null>;
+    /**
+     * The shared billing state for the scope, read when neither the statement
+     * nor the usage-limits body carries one. Null when it is not known.
+     */
+    readBillingState?: (scope: UsageScope) => Promise<SharedBillingState | null>;
     now(): Date;
 }
 export interface BillingUsageOptions {
@@ -91,7 +97,11 @@ export declare function resolveOnUsagePricing(limitsPlan: PricingPlan | null, su
 /** 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>;
+/** The usage report plus the shared billing state it was read with (US-025). */
+export type BillingUsageResult = BillingUsageReport & {
+    billingState?: SharedBillingState | null;
+};
+export declare function runBillingUsage(opts: BillingUsageOptions, deps: BillingUsageDeps): Promise<BillingUsageResult>;
 /**
  * `hq billing usage --card`: the card from GET /v1/pricing, or the bundled
  * card when the feed has none. Needs no sign-in.
@@ -99,6 +109,10 @@ export declare function runBillingUsage(opts: BillingUsageOptions, deps: Billing
 export declare function renderUsageCard(opts?: {
     json?: boolean;
     fetchPricing?: () => Promise<unknown | null>;
+    /** The caller's billing state, best effort. Absent or null prints the card alone. */
+    readState?: () => Promise<SharedBillingState | null>;
 }): Promise<string>;
+/** The text output: the report, then the account lines from the billing state. */
+export declare function formatUsageResult(report: BillingUsageResult, card: UsageCard): string;
 export declare function registerBillingUsageCommand(billing: Command): void;
 //# sourceMappingURL=billing-usage.d.ts.map

package/dist/commands/billing-usage.js

@@ -27,12 +27,13 @@
  * projected bill.
  */
 import chalk from "chalk";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { ensureCognitoToken, hasPersonCachedSession } from "../utils/cognito-session.js";
 import { vaultApiFetch, vaultApiFetchPublic } from "../utils/vault-api.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, hasBillingStateField, usageTrialActiveFromBody, } from "../lib/billing/usage-only.js";
+import { accountStatusLines } from "../lib/billing/billing-status-lines.js";
+import { fetchCompanyBillingSummary, pricingPlanFromBody, hasBillingStateField, readBillingState, usageTrialActiveFromBody, } from "../lib/billing/usage-only.js";
 export class UsageScopeError extends Error {
 }
 /** Pick the scope. Never reaches outside the caller's own memberships. */
@@ -153,9 +154,14 @@ export async function runBillingUsage(opts, deps) {
         })
         : null;
     const onUsagePricing = resolveOnUsagePricing(limitsPlan, pricingPlanFromSummary(summary));
+    const billingState = readBillingState(statement?.body) ??
+        readBillingState(limitsBody) ??
+        readBillingState(summary) ??
+        (deps.readBillingState ? await deps.readBillingState(scope).catch(() => null) : undefined);
+    const withState = (report) => billingState === undefined ? report : { ...report, billingState };
     if (onUsagePricing !== true)
-        return buildReadingsReport(usage, onUsagePricing);
-    return { ...buildReport(usage, ratesFromPricingStatement(pricing)), onUsagePricing: true };
+        return withState(buildReadingsReport(usage, onUsagePricing));
+    return withState({ ...buildReport(usage, ratesFromPricingStatement(pricing)), onUsagePricing: true });
 }
 // ── Production deps ─────────────────────────────────────────────────────────
 function productionDeps() {
@@ -223,6 +229,9 @@ function productionDeps() {
                 return null;
             return res.json().catch(() => null);
         },
+        async readBillingState(scope) {
+            return readBillingState(await this.fetchBillingSummary(scope));
+        },
         now: () => new Date(),
     };
 }
@@ -232,12 +241,44 @@ function productionDeps() {
  */
 export async function renderUsageCard(opts = {}) {
     const { card, source } = await fetchUsageCard(opts.fetchPricing ? { fetchPricing: opts.fetchPricing } : {});
-    if (opts.json)
-        return JSON.stringify({ source, card }, null, 2);
+    const state = opts.readState ? await opts.readState().catch(() => null) : null;
+    if (opts.json) {
+        return JSON.stringify({ source, card, ...(opts.readState ? { billingState: state } : {}) }, null, 2);
+    }
+    const account = accountStatusLines(state, card);
     const from = source === "feed"
         ? "from GET /v1/pricing"
         : "bundled copy; the pricing feed has no usage card yet";
-    return [`HQ usage pricing (card ${card.version}, ${from})`, "", ...formatUsageCardLines(card)].join("\n");
+    return [
+        `HQ usage pricing (card ${card.version}, ${from})`,
+        "",
+        ...formatUsageCardLines(card),
+        ...(account.length > 0 ? ["", "Your account:", ...account.map((l) => `  ${l}`)] : []),
+    ].join("\n");
+}
+/**
+ * The billing state for `--card`, only when a sign-in is already cached: the
+ * card needs no sign-in, so this never opens a browser login. Any failure is
+ * null and the card prints alone.
+ */
+async function cachedSessionBillingState(company) {
+    if (!hasPersonCachedSession())
+        return null;
+    const token = await ensureCognitoToken({ interactive: false });
+    const res = await vaultApiFetch({ token, path: "/membership/me" });
+    if (!res.ok)
+        return null;
+    const { companiesFromMemberships } = await import("./storage.js");
+    const scope = resolveUsageScope(companiesFromMemberships(await res.json()), { company });
+    if (scope.kind === "company")
+        return readBillingState(await fetchCompanyBillingSummary(token, scope.companyUid));
+    const person = await vaultApiFetch({ token, path: "/v1/billing/person/summary" });
+    return person.ok ? readBillingState(await person.json().catch(() => null)) : null;
+}
+/** The text output: the report, then the account lines from the billing state. */
+export function formatUsageResult(report, card) {
+    const account = accountStatusLines(report.billingState ?? null, card);
+    return account.length > 0 ? [formatReport(report), "", ...account].join("\n") : formatReport(report);
 }
 export function registerBillingUsageCommand(billing) {
     billing
@@ -252,12 +293,25 @@ export function registerBillingUsageCommand(billing) {
         .action(async function (opts) {
         try {
             if (opts.card) {
-                console.log(await renderUsageCard({ json: opts.json === true }));
+                const cardCompany = opts.company ?? this.parent?.opts().company;
+                console.log(await renderUsageCard({
+                    json: opts.json === true,
+                    readState: () => cachedSessionBillingState(cardCompany),
+                }));
                 return;
             }
             const parentCompany = this.parent?.opts().company ?? undefined;
             const report = await runBillingUsage({ ...opts, company: opts.company ?? parentCompany }, productionDeps());
-            console.log(opts.json ? JSON.stringify(report, null, 2) : formatReport(report));
+            if (opts.json) {
+                console.log(JSON.stringify(report, null, 2));
+            }
+            else if (report.billingState) {
+                const { card } = await fetchUsageCard();
+                console.log(formatUsageResult(report, card));
+            }
+            else {
+                console.log(formatReport(report));
+            }
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));

package/dist/commands/billing.d.ts

@@ -25,6 +25,17 @@
  * pricing: the flat-plan checkout is closed, so the CLI never opens it.
  */
 import { Command } from "commander";
+/** Shape of `GET /v1/billing/summary` we render. */
+interface BillingSummary {
+    subscriptionStatus: string | null;
+    defaultPaymentMethod: {
+        present: boolean;
+        brand: string | null;
+        last4: string | null;
+    };
+    databases?: DatabaseBilling | null;
+    [key: string]: unknown;
+}
 interface DatabaseBilling {
     period: string;
     activeApps: number;
@@ -37,6 +48,29 @@ interface DatabaseBilling {
     }>;
 }
 export declare function formatDatabaseBilling(db: DatabaseBilling | null | undefined): string[];
+/**
+ * The plan a person can act on, in words. The summary's `billingStatus.plan`
+ * is the Stripe webhook's label and says "usage" for ANY non-Workforce
+ * subscription (a metered usage subscription on a company that still prices
+ * as a flat plan reads "usage" there, hq-pro summary.ts). The plan the server
+ * actually prices by is `billingState.kind` (hq-pro #5088) or, on an older
+ * server, `pricingPlan`; `billingStatus.plan` only separates Workforce from
+ * the rest. DEV-5179: a reporter read "usage" off the status JSON while
+ * `hq billing usage` said "flat plan"; both were right about different fields.
+ */
+export declare function describePlan(summary: BillingSummary): string;
+export declare const PLAN_UNAVAILABLE = "unavailable right now";
+/**
+ * A scheduled switch to usage pricing (hq-pro US-014 `GET
+ * /v1/billing/usage-switch`), or null. The route is owner-only and absent on
+ * older servers. A refusal (403, 404) reads as "nothing scheduled"; any other
+ * failure is "unreadable" so the status view can say so instead of implying
+ * no switch. The status view never fails on it.
+ */
+export declare function fetchScheduledUsageSwitch(token: string, companyUid: string): Promise<{
+    switchDate: string;
+    phase: "scheduled" | "preview";
+} | "unreadable" | null>;
 export declare function registerBillingCommand(program: Command): void;
 export {};
 //# sourceMappingURL=billing.d.ts.map