@indigoai-us/hq-cli 5.345.163 → 5.345.164

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [Unreleased]
 
+## [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/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

package/dist/commands/billing.js

@@ -30,8 +30,9 @@ import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 import { mintPaymentLink } from "../utils/billing-gate.js";
 import { openUsageSwitch } from "../utils/team-upgrade.js";
 import { registerBillingSponsorCommands } from "./billing-sponsor.js";
-import { fetchCompanyPricingPlan, isUsageOnly, usageOnlyUpgradeLines, } from "../lib/billing/usage-only.js";
+import { fetchCompanyPricingPlan, isUsageOnly, pricingPlanFromBody, readBillingState, usageOnlyUpgradeLines, } from "../lib/billing/usage-only.js";
 import { fetchUsageCard } from "../lib/billing/usage-card.js";
+import { accountStatusLines } from "../lib/billing/billing-status-lines.js";
 import { registerBillingUsageCommand } from "./billing-usage.js";
 const CHARGED_ON = {
     team: "the Team subscription",
@@ -62,6 +63,94 @@ export function formatDatabaseBilling(db) {
     }
     return lines;
 }
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * 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 function describePlan(summary) {
+    const state = readBillingState(summary);
+    if (state) {
+        switch (state.kind) {
+            case "usage":
+                return "usage pricing";
+            case "usage-trial":
+                return state.trial
+                    ? `usage pricing (trial, ${state.trial.daysLeft} days left)`
+                    : "usage pricing (trial)";
+            case "legacy-payer":
+                // legacy-payer also covers invoice-billed companies, which have no
+                // Workforce subscription behind them.
+                return asRecord(summary.billingStatus)?.plan === "team"
+                    ? "Workforce (flat plan)"
+                    : "flat plan (billed by invoice)";
+            case "legacy-free":
+                return "Starter (free)";
+            case "enterprise":
+                return "Enterprise";
+            case "comped":
+                return "comped (not billed)";
+        }
+    }
+    if (pricingPlanFromBody(summary) === "usage-only")
+        return "usage pricing";
+    if (pricingPlanFromBody(summary) === "current") {
+        // An older server says "flat plan" but not which one: only a Workforce
+        // subscription is visible here, so anything else is named no further.
+        return asRecord(summary.billingStatus)?.plan === "team" ? "Workforce (flat plan)" : "flat plan";
+    }
+    // The server did not say which plan prices this company. Naming one here
+    // would guess, and a guess of "Starter (free)" told a paying company it was
+    // on the free plan.
+    return PLAN_UNAVAILABLE;
+}
+export const PLAN_UNAVAILABLE = "unavailable right now";
+/** True when the plan description already says the company prices by usage. */
+function isUsagePricingLabel(label) {
+    return label.startsWith("usage pricing");
+}
+/**
+ * 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 async function fetchScheduledUsageSwitch(token, companyUid) {
+    try {
+        const res = await vaultApiFetch({
+            token,
+            path: "/v1/billing/usage-switch",
+            query: { companyUid },
+        });
+        if (res.status === 403 || res.status === 404)
+            return null;
+        if (!res.ok)
+            return "unreadable";
+        const body = asRecord(await res.json());
+        const phase = body?.phase;
+        const switchDate = body?.switchDate;
+        if ((phase === "scheduled" || phase === "preview") &&
+            typeof switchDate === "string" &&
+            Number.isFinite(Date.parse(switchDate))) {
+            return { switchDate, phase };
+        }
+        return null;
+    }
+    catch {
+        return "unreadable";
+    }
+}
 function fail(err) {
     console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
     process.exit(1);
@@ -101,6 +190,18 @@ export function registerBillingCommand(program) {
             }
             const sub = summary.subscriptionStatus ?? "none";
             console.log(`${chalk.bold("Subscription")}: ${sub}`);
+            const planLabel = describePlan(summary);
+            console.log(`${chalk.bold("Plan")}: ${planLabel}`);
+            if (!isUsagePricingLabel(planLabel) && planLabel !== PLAN_UNAVAILABLE) {
+                const scheduled = await fetchScheduledUsageSwitch(token, companyUid);
+                if (scheduled === "unreadable") {
+                    console.log("  Switch to usage pricing: could not be read right now.");
+                }
+                else if (scheduled) {
+                    console.log(`  Switch to usage pricing scheduled for ${scheduled.switchDate.slice(0, 10)}` +
+                        (scheduled.phase === "preview" ? " (preview window open)." : "."));
+                }
+            }
             const pm = summary.defaultPaymentMethod;
             if (pm?.present) {
                 const detail = pm.brand && pm.last4 ? `${pm.brand} ••••${pm.last4}` : "on file";
@@ -110,6 +211,12 @@ export function registerBillingCommand(program) {
                 console.log(`${chalk.bold("Card")}: ${chalk.yellow("no card on file")} — ` +
                     `run \`hq billing checkout\` to add one before provisioning paid resources.`);
             }
+            const state = readBillingState(summary);
+            if (state && (state.kind === "usage" || state.kind === "usage-trial")) {
+                const { card } = await fetchUsageCard();
+                for (const line of accountStatusLines(state, card))
+                    console.log(line);
+            }
             for (const line of formatDatabaseBilling(summary.databases))
                 console.log(line);
         }

package/dist/commands/deploy-domains.d.ts

@@ -17,6 +17,8 @@ export declare const deployDomainsPrompt: {
 };
 /** The sentence `buy` adds when the order's outcome is not known. */
 export declare function resumeOrderSentence(idempotencyKey: string): string;
+/** Shown when hq-pro registered the domain but could not capture the card charge. */
+export declare function retryChargeSentence(idempotencyKey: string): string;
 interface Binding {
     appId: string;
     orgSlug?: string;

package/dist/commands/deploy-domains.js

@@ -117,6 +117,10 @@ const SETTLED_PURCHASE_CODES = new Set([
 export function resumeOrderSentence(idempotencyKey) {
     return `The order may still be in progress. Run the same command again with --idempotency-key ${idempotencyKey} to finish or check it. Do not start a new order.`;
 }
+/** Shown when hq-pro registered the domain but could not capture the card charge. */
+export function retryChargeSentence(idempotencyKey) {
+    return `Run the same command again with --idempotency-key ${idempotencyKey} to retry the charge. Do not start a new order.`;
+}
 /** The registrant fields hq-pro accepts; nothing else from the file is sent. */
 const REGISTRANT_FIELDS = [
     "firstName", "lastName", "companyName", "address1", "address2",
@@ -312,16 +316,18 @@ async function resolveTarget(token, options) {
     if (!binding.orgSlug && options.company === undefined) {
         throw new DeployDomainsError("The folder's link does not name a company. Pass --company <slug>, or re-link the folder.", "COMPANY_REQUIRED");
     }
-    if (binding.orgSlug && options.company !== undefined && options.company !== binding.orgSlug) {
+    if (binding.orgSlug && options.company !== undefined && options.company.toLowerCase() !== binding.orgSlug) {
         throw new DeployDomainsError(`This folder is linked to an app in '${binding.orgSlug}', not '${displayText(options.company)}'. Drop --company, or pass --app <name or id>.`, "COMPANY_MISMATCH");
     }
     return {
         appId: binding.appId,
-        orgSlug: resolveSlug(options.company, binding.orgSlug),
+        // A matching --company may differ only in case; the link's slug is canonical.
+        orgSlug: binding.orgSlug ?? resolveSlug(options.company, undefined),
         appLabel: binding.appId,
     };
 }
 const HOSTNAME_LABEL = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const ALL_DIGITS = /^\d+$/;
 /**
  * Normalize a domain to the ASCII form the server stores, using the same
  * hostname rule hq-deploy's validateAppHostname enforces: at least two
@@ -344,6 +350,13 @@ export function normalizeDomain(raw) {
     if (labels.length < 2 || labels.some((label) => label.length > 63 || !HOSTNAME_LABEL.test(label))) {
         throw invalid();
     }
+    // domainToASCII applies WHATWG IPv4 parsing ("1.2" becomes "1.0.0.2",
+    // "0x7f.1" becomes "127.0.0.1"), and a name it cannot parse as one comes
+    // back empty. No real top-level domain is numeric, so a numeric last label
+    // after the conversion is an address.
+    if (ALL_DIGITS.test(labels[labels.length - 1])) {
+        throw invalid();
+    }
     return domain;
 }
 function domainRoute(appId, domain, suffix = "") {
@@ -727,8 +740,10 @@ async function buyAction(domainArg, options) {
     }
     else if (body.paymentCaptured === false) {
         // hq-pro registered the name, but capturing the card authorization failed.
+        // A retry with the same key retrieves the same authorization, replays the
+        // registration for this order and captures again (hq-pro domain-purchase.ts).
         console.log(`Registered ${displayText(domain)}.${expires} The card was authorized for ${usd(expectedPriceUsd)}, ` +
-            `but the charge has not completed yet. HQ billing follows up on it. Do not buy the domain again.`);
+            `but the charge did not complete. ${retryChargeSentence(idempotencyKey)}`);
     }
     else {
         console.log(`Bought ${displayText(domain)} for ${usd(expectedPriceUsd)}.${expires}`);

package/dist/lib/billing/billing-status-lines.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The account lines `hq billing status`, `hq billing usage` and
+ * `hq billing usage --card` print from hq-pro's shared `billingState` (US-025).
+ * One helper so every surface shows the same trial usage, included usage,
+ * spend limit and card prompt for the same state.
+ */
+import { type UsageCard } from "./usage-card.js";
+import type { SharedBillingState } from "./usage-only.js";
+/**
+ * Lines for one billing state. Legacy, enterprise and comped accounts get no
+ * lines. The member view carries no money figures, so it gets none either.
+ */
+export declare function accountStatusLines(state: SharedBillingState | null, card?: UsageCard): string[];
+//# sourceMappingURL=billing-status-lines.d.ts.map

package/dist/lib/billing/billing-status-lines.js

@@ -0,0 +1,43 @@
+/**
+ * The account lines `hq billing status`, `hq billing usage` and
+ * `hq billing usage --card` print from hq-pro's shared `billingState` (US-025).
+ * One helper so every surface shows the same trial usage, included usage,
+ * spend limit and card prompt for the same state.
+ */
+import { BUNDLED_USAGE_CARD, formatCardUsd } from "./usage-card.js";
+function usd(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}
+function onUsagePricing(state) {
+    return state.kind === "usage" || state.kind === "usage-trial";
+}
+/**
+ * Lines for one billing state. Legacy, enterprise and comped accounts get no
+ * lines. The member view carries no money figures, so it gets none either.
+ */
+export function accountStatusLines(state, card = BUNDLED_USAGE_CARD) {
+    if (!state || !onUsagePricing(state))
+        return [];
+    const lines = [];
+    if (state.kind === "usage-trial" && state.trial) {
+        lines.push(`Trial: ${state.trial.daysLeft} days left (ends ${state.trial.endsAt.slice(0, 10)})`);
+        if (state.view === "full" && state.trial.usedCents !== null) {
+            const capCents = state.trial.capCents ?? card.trial.capUsd * 100;
+            lines.push(`Trial usage: ${usd(state.trial.usedCents)} of the ${usd(capCents)} trial cap`);
+        }
+    }
+    if (state.view !== "full")
+        return lines;
+    lines.push(`Included usage: ${formatCardUsd(card.includedUsd)} each month`);
+    if (state.spendLimit) {
+        lines.push(state.spendLimit.cents === null
+            ? "Spend limit: none set"
+            : `Spend limit: ${usd(state.spendLimit.cents)} a month`);
+    }
+    if (state.cardPrompt) {
+        lines.push(`Add a card: usage is past the ${formatCardUsd(card.includedUsd)} included this month. ` +
+            "Run `hq billing checkout` to keep working past it.");
+    }
+    return lines;
+}
+//# sourceMappingURL=billing-status-lines.js.map

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

@@ -35,10 +35,28 @@ export interface SharedBillingState {
     kind: BillingStateKind;
     scope: "company" | "person";
     view: "full" | "member";
+    /**
+     * The usage trial, or null. `capCents` is the trial's usage cap and
+     * `usedCents` what the trial has used so far; both are null when the server
+     * does not say (member view, older server).
+     */
     trial: {
         daysLeft: number;
         endsAt: string;
+        capCents: number | null;
+        usedCents: number | null;
+    } | null;
+    /**
+     * The monthly spend limit. `cents: null` means no limit is set. The whole
+     * field is null off usage pricing and in the member view.
+     */
+    spendLimit: {
+        cents: number | null;
     } | null;
+    /** Whether a card is on file. Null when the server does not say. */
+    cardOnFile: boolean | null;
+    /** Usage passed the included allowance with no card on file. */
+    cardPrompt: boolean;
     /** A pause the server is applying now, or null. */
     paused: {
         reason: string;

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

@@ -65,7 +65,21 @@ function readTrial(value) {
         !Number.isFinite(Date.parse(trial.endsAt))) {
         return undefined;
     }
-    return { daysLeft: trial.daysLeft, endsAt: trial.endsAt };
+    return {
+        daysLeft: trial.daysLeft,
+        endsAt: trial.endsAt,
+        capCents: centsOrNull(trial.capCents),
+        usedCents: centsOrNull(trial.usedCents),
+    };
+}
+function centsOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function readSpendLimit(value) {
+    const limit = asRecord(value);
+    if (!limit)
+        return null;
+    return { cents: centsOrNull(limit.cents) };
 }
 function readPaused(value) {
     const paused = asRecord(value);
@@ -102,6 +116,9 @@ export function readBillingState(body) {
         scope: state.scope,
         view: state.view,
         trial,
+        spendLimit: readSpendLimit(state.spendLimit),
+        cardOnFile: typeof state.cardOnFile === "boolean" ? state.cardOnFile : null,
+        cardPrompt: state.cardPrompt === true,
         paused: readPaused(state.paused),
         actions: {
             addCard: actions?.addCard === true,

package/dist/lib/doctor/checks/sync-runtime.d.ts

@@ -1,13 +1,47 @@
+import { readSessionCompanyLock } from "../../session-company-lock.js";
 import type { CheckResult } from "../types.js";
 export declare const SYNC_RUNTIME_WINDOW_MS: number;
 /** Ignore timing and restart signals until a newly started receiver has settled. */
 export declare const SYNC_RUNTIME_RESTART_WARMUP_MS: number;
+/** Most refused vault keys named by `sync.runtime.pull-access-denied`. */
+export declare const PULL_DENIED_KEY_CAP = 10;
+/** A key refused on at least this many pulls in the hour is a standing condition, not a one-off. */
+export declare const PULL_DENIED_MIN_REPEATS = 2;
 export interface SyncRuntimeOptions {
     now: number;
     conflictCount?: number;
+    /**
+     * Company scopes whose refused vault keys may be named. `undefined` means
+     * the session holds no company lock, so every scope may be named. Keys in
+     * any other scope (including `personal` when it is not listed) are counted
+     * but never named, so `hq doctor` in a session locked to company A cannot
+     * print company B's file names from the machine-wide sync log.
+     */
+    nameableCompanies?: readonly string[];
 }
+/**
+ * Which cloud call a receiver permission refusal came from. Closed vocabulary
+ * derived from the hq-cloud receiver's event names, so the breakdown can be
+ * reported without the error prose.
+ *
+ *   - `subscribe`: `POST /v1/sync/subscribe` itself answered 403 while the
+ *     receiver re-vended its queue credentials.
+ *   - `sqs-receive` / `sqs-visibility` / `sqs-delete`: the per-device queue
+ *     credentials vended by subscribe were refused by SQS. One bad vend
+ *     repeats on every poll and lease heartbeat until the runner restarts.
+ *   - `cloudwatch-metric`: the latency metric publisher was refused.
+ *   - `targeted-pull`: the object pull after a change event failed; the
+ *     refused keys are named by `sync.runtime.pull-access-denied`.
+ *   - `runner-error`: a runner `error` record outside the receiver.
+ */
+export type ReceiverRefusalCall = "subscribe" | "sqs-receive" | "sqs-visibility" | "sqs-delete" | "cloudwatch-metric" | "targeted-pull" | "runner-error" | "other";
 /** Classify the last hour of sync log lines into privacy-safe results. */
 export declare function analyzeSyncRuntimeLog(lines: readonly string[], options: SyncRuntimeOptions): CheckResult[];
+/**
+ * Company scopes this session may see named: `undefined` (all) when there is
+ * no session or no company lock; nothing when the lock cannot be verified.
+ */
+export declare function sessionNameableCompanies(env: NodeJS.ProcessEnv, readLock?: typeof readSessionCompanyLock): readonly string[] | undefined;
 /** Read the machine's sync logs and client health file. */
 export declare function defaultSyncRuntimeResults(now: Date, hqHome?: string, env?: NodeJS.ProcessEnv): CheckResult[];
 //# sourceMappingURL=sync-runtime.d.ts.map