@indigoai-us/hq-cli 5.345.162 → 5.345.164

package/dist/commands/feedback-triage.d.ts

@@ -0,0 +1,67 @@
+import { Command } from "commander";
+/**
+ * Staff triage commands on the feedback queue: `hq feedback list`,
+ * `hq feedback triage` and `hq feedback close`. `hq feedback assign` lives in
+ * feedback.ts next to the shared helpers.
+ *
+ * The server owns triagedAt, triagedBy and priority. These commands never
+ * send them.
+ */
+export declare const TRIAGE_KINDS: readonly ["bug", "feature", "question"];
+export type TriageKind = (typeof TRIAGE_KINDS)[number];
+export declare const MAX_TRIAGE_SUMMARY = 2000;
+export declare const DEFAULT_LIST_LIMIT = 50;
+export interface FeedbackListRow {
+    id: string;
+    title?: string;
+    plan?: string;
+    submittedAt?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export type FeedbackListSelector = {
+    kind: "untriaged";
+} | {
+    kind: "assignee";
+    assignee: string;
+};
+/** Email claim of the caller's staff token, used by `list --mine`. */
+export declare function emailFromToken(token: string): string | null;
+/** Compact age such as `5m`, `3h` or `2d`. Unknown or unparsable times print `-`. */
+export declare function formatFeedbackAge(iso: string | undefined, now?: number): string;
+/**
+ * hq-pro's `GET /v1/feedback` returns the next page as `nextCursor` on every
+ * path (the untriaged queue also mirrors it as `cursor`) and reads it back from
+ * `?cursor=`. `nextToken` is accepted for older servers. The value always goes
+ * back as `?cursor=`.
+ */
+export declare function cursorFrom(data: unknown): string | null;
+/** Page through `GET /v1/feedback` until `limit` rows (or every row with `limit: null`). */
+export declare function listFeedback(opts: {
+    token: string;
+    selector: FeedbackListSelector;
+    status?: string;
+    limit: number | null;
+}): Promise<FeedbackListRow[]>;
+export declare function formatFeedbackTable(rows: FeedbackListRow[], now?: number): string;
+export declare function parseListLimit(raw: string): number;
+export declare function buildTriagePatch(opts: {
+    id: string;
+    kind: string;
+    area: string;
+    summary: string;
+    duplicateOf?: string;
+}): Record<string, string>;
+export declare function buildClosePatch(opts: {
+    reason: string;
+    wontFix?: boolean;
+}): Record<string, string>;
+/** PATCH one feedback row; returns the server's JSON, or the sent fields when the body is empty. */
+export declare function patchFeedback(opts: {
+    id: string;
+    token: string;
+    body: Record<string, string>;
+    action: string;
+}): Promise<unknown>;
+export declare function registerFeedbackTriageCommands(feedbackCmd: Command): void;
+//# sourceMappingURL=feedback-triage.d.ts.map

package/dist/commands/feedback-triage.js

@@ -0,0 +1,294 @@
+import chalk from "chalk";
+import { assertVaultApiRequestSupported, vaultApiFetch } from "../utils/vault-api.js";
+import { decodeJwtPayload } from "../utils/person-token-cache.js";
+import { assertFeedbackId, normalizeFeedbackAssignee, readFeedbackError, resolveStaffToken, } from "./feedback.js";
+/**
+ * Staff triage commands on the feedback queue: `hq feedback list`,
+ * `hq feedback triage` and `hq feedback close`. `hq feedback assign` lives in
+ * feedback.ts next to the shared helpers.
+ *
+ * The server owns triagedAt, triagedBy and priority. These commands never
+ * send them.
+ */
+export const TRIAGE_KINDS = ["bug", "feature", "question"];
+export const MAX_TRIAGE_SUMMARY = 2000;
+export const DEFAULT_LIST_LIMIT = 50;
+/** Safety stop for --all so a server that never ends its cursor can't loop forever. */
+const MAX_LIST_PAGES = 100;
+function fail(err) {
+    console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+    process.exit(1);
+}
+/** Email claim of the caller's staff token, used by `list --mine`. */
+export function emailFromToken(token) {
+    const claims = decodeJwtPayload(token);
+    const email = claims?.email;
+    return typeof email === "string" && email.includes("@") ? email.toLowerCase() : null;
+}
+/** Compact age such as `5m`, `3h` or `2d`. Unknown or unparsable times print `-`. */
+export function formatFeedbackAge(iso, now = Date.now()) {
+    if (!iso)
+        return "-";
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return "-";
+    const minutes = Math.max(0, Math.floor((now - at) / 60_000));
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+function rowsFrom(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return [];
+    const items = data.items;
+    if (!Array.isArray(items))
+        return [];
+    return items.filter((row) => !!row && typeof row === "object" && typeof row.id === "string");
+}
+/**
+ * hq-pro's `GET /v1/feedback` returns the next page as `nextCursor` on every
+ * path (the untriaged queue also mirrors it as `cursor`) and reads it back from
+ * `?cursor=`. `nextToken` is accepted for older servers. The value always goes
+ * back as `?cursor=`.
+ */
+export function cursorFrom(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return null;
+    for (const name of ["nextCursor", "cursor", "nextToken"]) {
+        const value = data[name];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return null;
+}
+/** Server page cap (FEEDBACK_LIST_PAGE_MAX). The plain list path rejects a cursor without a limit. */
+const LIST_PAGE_SIZE = 200;
+/** Page through `GET /v1/feedback` until `limit` rows (or every row with `limit: null`). */
+export async function listFeedback(opts) {
+    const base = opts.selector.kind === "untriaged"
+        ? { triage: "untriaged" }
+        : { assignee: opts.selector.assignee };
+    if (opts.status)
+        base.status = opts.status;
+    const rows = [];
+    let cursor = null;
+    for (let page = 0; page < MAX_LIST_PAGES; page++) {
+        const pageSize = opts.limit === null ? LIST_PAGE_SIZE : Math.min(LIST_PAGE_SIZE, opts.limit - rows.length);
+        const query = { ...base, limit: String(pageSize) };
+        if (cursor)
+            query.cursor = cursor;
+        const res = await vaultApiFetch({ token: opts.token, path: "/v1/feedback", query });
+        if (!res.ok) {
+            throw new Error(`Failed to list feedback: ${await readFeedbackError(res)}`);
+        }
+        const data = (await res.json());
+        rows.push(...rowsFrom(data));
+        if (opts.limit !== null && rows.length >= opts.limit)
+            return rows.slice(0, opts.limit);
+        cursor = cursorFrom(data);
+        if (!cursor)
+            return rows;
+    }
+    return rows;
+}
+export function formatFeedbackTable(rows, now = Date.now()) {
+    const header = ["ID", "AGE", "PLAN", "TITLE"];
+    const body = rows.map((row) => [
+        row.id,
+        formatFeedbackAge(row.submittedAt ?? row.createdAt, now),
+        typeof row.plan === "string" && row.plan.length > 0 ? row.plan : "-",
+        typeof row.title === "string" ? row.title : "",
+    ]);
+    const widths = [0, 1, 2].map((col) => Math.max(header[col].length, ...body.map((cells) => cells[col].length)));
+    return [header, ...body]
+        .map((cells) => cells.map((cell, col) => (col < 3 ? cell.padEnd(widths[col]) : cell)).join("  ").trimEnd())
+        .join("\n");
+}
+export function parseListLimit(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`Invalid --limit '${raw}': expected a positive whole number.`);
+    }
+    return n;
+}
+export function buildTriagePatch(opts) {
+    if (!TRIAGE_KINDS.includes(opts.kind)) {
+        throw new Error(`Invalid --kind '${opts.kind}': expected one of ${TRIAGE_KINDS.join(", ")}.`);
+    }
+    const area = opts.area.trim();
+    if (!area)
+        throw new Error("--area must not be empty.");
+    const summary = opts.summary.trim();
+    if (!summary)
+        throw new Error("--summary must not be empty.");
+    if (summary.length > MAX_TRIAGE_SUMMARY) {
+        throw new Error(`--summary is ${summary.length} characters; the limit is ${MAX_TRIAGE_SUMMARY}.`);
+    }
+    const body = {
+        triageStatus: opts.duplicateOf === undefined ? "triaged" : "duplicate",
+        triageKind: opts.kind,
+        area,
+        summary,
+    };
+    if (opts.duplicateOf !== undefined) {
+        assertFeedbackId(opts.duplicateOf);
+        if (opts.duplicateOf === opts.id) {
+            throw new Error("--duplicate-of must name a different feedback item.");
+        }
+        body.duplicateOf = opts.duplicateOf;
+    }
+    return body;
+}
+export function buildClosePatch(opts) {
+    const reason = opts.reason.trim();
+    if (!reason)
+        throw new Error("--reason must not be empty.");
+    return { status: opts.wontFix ? "wont_fix" : "resolved", resolution: reason };
+}
+/** PATCH one feedback row; returns the server's JSON, or the sent fields when the body is empty. */
+export async function patchFeedback(opts) {
+    const res = await vaultApiFetch({
+        token: opts.token,
+        path: `/v1/feedback/${opts.id}`,
+        method: "PATCH",
+        body: opts.body,
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to ${opts.action} ${opts.id}: ${await readFeedbackError(res)}`);
+    }
+    const data = (await res.json().catch(() => null));
+    return data ?? { id: opts.id, ...opts.body };
+}
+function registerListSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("list")
+        .description("List feedback: untriaged (default), yours, or one person's")
+        .option("--untriaged", "Items nobody has triaged yet (the default)")
+        .option("--mine", "Items assigned to you")
+        .option("--assignee <person>", "Items assigned to this email address or prs_ uid")
+        .option("--status <status>", "Only items with this status")
+        .option("--limit <n>", `Stop after this many items (default ${DEFAULT_LIST_LIMIT})`)
+        .option("--all", "Fetch every page")
+        .option("--json", "Print { items, count } as JSON")
+        .action(async (opts) => {
+        try {
+            const picked = [opts.untriaged, opts.mine, opts.assignee !== undefined].filter(Boolean);
+            if (picked.length > 1) {
+                throw new Error("Use only one of --untriaged, --mine and --assignee.");
+            }
+            if (opts.all && opts.limit !== undefined) {
+                throw new Error("Use --limit or --all, not both.");
+            }
+            if (opts.status !== undefined && !opts.status.trim()) {
+                throw new Error("--status must not be empty.");
+            }
+            const limit = opts.all
+                ? null
+                : opts.limit === undefined
+                    ? DEFAULT_LIST_LIMIT
+                    : parseListLimit(opts.limit);
+            const token = await resolveStaffToken();
+            let selector = { kind: "untriaged" };
+            if (opts.mine) {
+                const email = emailFromToken(token);
+                if (!email) {
+                    throw new Error("--mine needs a person login with an email (hq login). Use --assignee <person> instead.");
+                }
+                selector = { kind: "assignee", assignee: email };
+            }
+            else if (opts.assignee !== undefined) {
+                selector = {
+                    kind: "assignee",
+                    assignee: normalizeFeedbackAssignee(opts.assignee, "--assignee"),
+                };
+            }
+            assertVaultApiRequestSupported({ token, path: "/v1/feedback" });
+            const items = await listFeedback({
+                token,
+                selector,
+                status: opts.status?.trim(),
+                limit,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify({ items, count: items.length }));
+            }
+            else if (items.length === 0) {
+                console.log("No feedback items match.");
+            }
+            else {
+                console.log(formatFeedbackTable(items));
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+function registerTriageSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("triage")
+        .description("Label a feedback item with its kind, area and summary, or mark it a duplicate")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .requiredOption("--kind <kind>", `One of ${TRIAGE_KINDS.join(", ")}`)
+        .requiredOption("--area <area>", "Product area, for example sync or desktop")
+        .requiredOption("--summary <text>", `One-line triage summary (at most ${MAX_TRIAGE_SUMMARY} characters)`)
+        .option("--duplicate-of <id>", "Mark this item a duplicate of another feedback id")
+        .option("--json", "Print the updated item as JSON")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            const body = buildTriagePatch({ id, ...opts });
+            const token = await resolveStaffToken();
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            const result = await patchFeedback({ id, token, body, action: "triage" });
+            if (opts.json) {
+                console.log(JSON.stringify(result));
+            }
+            else if (body.duplicateOf) {
+                console.log(`Marked duplicate: ${id} -> ${body.duplicateOf}`);
+            }
+            else {
+                console.log(`Triaged: ${id} (${body.triageKind}, ${body.area})`);
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+function registerCloseSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("close")
+        .description("Close a feedback item as resolved (or won't fix) with a reason")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .requiredOption("--reason <text>", "Why it is closed: the fix, PR or version, or the decision")
+        .option("--wont-fix", "Close as won't fix instead of resolved")
+        .option("--json", "Print the updated item as JSON")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            const body = buildClosePatch(opts);
+            const token = await resolveStaffToken();
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            const result = await patchFeedback({ id, token, body, action: "close" });
+            if (opts.json) {
+                console.log(JSON.stringify(result));
+            }
+            else {
+                console.log(`Closed: ${id} (${body.status})`);
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+export function registerFeedbackTriageCommands(feedbackCmd) {
+    registerListSubcommand(feedbackCmd);
+    registerTriageSubcommand(feedbackCmd);
+    registerCloseSubcommand(feedbackCmd);
+}
+//# sourceMappingURL=feedback-triage.js.map

package/dist/commands/feedback.d.ts

@@ -76,6 +76,13 @@ export declare function submitFeedback(opts: FeedbackSubmitOptions): Promise<Fee
 export declare const PUBLIC_TICKET_STATES: readonly ["triaged", "in-progress", "shipped", "verified", "resolved"];
 export type PublicTicketState = (typeof PUBLIC_TICKET_STATES)[number];
 export declare function assertFeedbackId(id: string): void;
+/**
+ * The staff feedback routes gate on the id token's email claim, so send the
+ * cached id token when a person session has one. Machine identities already
+ * get their id token back from ensureCognitoToken.
+ */
+export declare function resolveStaffToken(): Promise<string>;
+export declare function readFeedbackError(res: Response): Promise<string>;
 /** Resolve (and lazily mint) the public tracking link for a ticket. */
 export declare function fetchFeedbackLink(opts: {
     id: string;
@@ -92,7 +99,7 @@ export declare function postFeedbackUpdate(opts: {
     slack: string | null;
 }>;
 /** Mirror of hq-pro normalizeAssignee: a prs_ uid as-is, an email lowercased. */
-export declare function normalizeFeedbackAssignee(value: string): string;
+export declare function normalizeFeedbackAssignee(value: string, label?: string): string;
 /**
  * Reassign a ticket. A person's own login may move a ticket that another
  * person claimed; agent and operator service tokens get 409
@@ -103,5 +110,10 @@ export declare function assignFeedback(opts: {
     token: string;
     assignee: string;
 }): Promise<void>;
+/**
+ * Pick the new assignee from the positional `[person]` or the `--to` flag.
+ * Either form works; naming two different people is an error.
+ */
+export declare function resolveAssignTarget(person: string | undefined, to: string | undefined): string;
 export declare function registerFeedbackCommand(program: Command): void;
 //# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -9,6 +9,7 @@ import { uploadLogBundle } from "../utils/feedback-log-bundle.js";
 import { resolveProcessFlagGate } from "../lib/flag-registry.js";
 import { cachedLatestVersion } from "../utils/version-check.js";
 import { registerFeedbackShowCommand } from "./feedback-show.js";
+import { registerFeedbackTriageCommands } from "./feedback-triage.js";
 export const FEEDBACK_LATEST_VERSION_FLAG = "feedback.latest-version";
 export const FEEDBACK_LATEST_VERSION_FLAG_FALLBACK = false;
 export const FEEDBACK_REPORTER_KIND_FLAG = "feedback.reporter-kind";
@@ -229,14 +230,14 @@ export function assertFeedbackId(id) {
  * cached id token when a person session has one. Machine identities already
  * get their id token back from ensureCognitoToken.
  */
-async function resolveStaffToken() {
+export async function resolveStaffToken() {
     const token = await ensureCognitoToken({ interactive: false });
     const cached = loadCachedTokens();
     return typeof cached?.idToken === "string" && cached.idToken.length > 0
         ? cached.idToken
         : token;
 }
-async function readFeedbackError(res) {
+export async function readFeedbackError(res) {
     const data = await res.json().catch(() => ({}));
     return data &&
         typeof data === "object" &&
@@ -287,10 +288,10 @@ export async function postFeedbackUpdate(opts) {
 }
 const ASSIGNEE_RE = /^(?:prs_[A-Za-z0-9]+|[^\s@]+@[^\s@]+\.[^\s@]+)$/;
 /** Mirror of hq-pro normalizeAssignee: a prs_ uid as-is, an email lowercased. */
-export function normalizeFeedbackAssignee(value) {
+export function normalizeFeedbackAssignee(value, label = "--to") {
     const trimmed = value.trim();
     if (!ASSIGNEE_RE.test(trimmed)) {
-        throw new Error(`Invalid --to '${value}': expected an email address or a prs_ uid.`);
+        throw new Error(`Invalid ${label} '${value}': expected an email address or a prs_ uid.`);
     }
     return trimmed.startsWith("prs_") ? trimmed : trimmed.toLowerCase();
 }
@@ -315,20 +316,42 @@ export async function assignFeedback(opts) {
     }
     throw new Error(`Failed to assign ${opts.id}: ${message}`);
 }
+/**
+ * Pick the new assignee from the positional `[person]` or the `--to` flag.
+ * Either form works; naming two different people is an error.
+ */
+export function resolveAssignTarget(person, to) {
+    if (person === undefined && to === undefined) {
+        throw new Error("Name the new assignee: hq feedback assign <id> <person> (or --to <person>).");
+    }
+    const fromPerson = person === undefined ? undefined : normalizeFeedbackAssignee(person, "person");
+    const fromTo = to === undefined ? undefined : normalizeFeedbackAssignee(to);
+    if (fromPerson !== undefined && fromTo !== undefined && fromPerson !== fromTo) {
+        throw new Error(`Conflicting assignees '${person}' and --to '${to}': give only one.`);
+    }
+    return (fromPerson ?? fromTo);
+}
 function registerAssignSubcommand(feedbackCmd) {
     feedbackCmd
         .command("assign")
         .description("Reassign a ticket to a person, including one another person has claimed")
         .argument("<id>", "Feedback id (feedback_<uuid>)")
-        .requiredOption("--to <assignee>", "New assignee: an email address or a prs_ uid")
-        .action(async (id, opts) => {
+        .argument("[person]", "New assignee: an email address or a prs_ uid")
+        .option("--to <assignee>", "New assignee: an email address or a prs_ uid")
+        .option("--json", "Print the result as JSON")
+        .action(async (id, person, opts) => {
         try {
             assertFeedbackId(id);
-            const assignee = normalizeFeedbackAssignee(opts.to);
+            const assignee = resolveAssignTarget(person, opts.to);
             const token = await resolveStaffToken();
             assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
             await assignFeedback({ id, token, assignee });
-            console.log(`Assigned: ${id} -> ${assignee}`);
+            if (opts.json) {
+                console.log(JSON.stringify({ id, assignee }));
+            }
+            else {
+                console.log(`Assigned: ${id} -> ${assignee}`);
+            }
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -499,5 +522,6 @@ export function registerFeedbackCommand(program) {
     registerUpdateSubcommand(feedbackCmd);
     registerFeedbackShowCommand(feedbackCmd);
     registerAssignSubcommand(feedbackCmd);
+    registerFeedbackTriageCommands(feedbackCmd);
 }
 //# sourceMappingURL=feedback.js.map

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