@indigoai-us/hq-cli 5.76.0 → 5.77.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.77.1]
+
+### Fixed
+
+- Missing company-slug responses are classified as expected user errors, so the
+  CLI no longer sends this expected absence to Sentry.
+
 ## [5.71.0]
 
 ### Added

package/dist/commands/agents.js

@@ -25,7 +25,7 @@ import chalk from "chalk";
 import { randomUUID } from "node:crypto";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
-import { AGENT_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingRequired, } from "../utils/billing-gate.js";
+import { AGENT_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
     "minimal",
@@ -64,7 +64,12 @@ export async function agentsRequest(opts) {
     const res = await vaultApiFetch(opts);
     if (!res.ok) {
         const body = (await res.json().catch(() => ({})));
-        throw new AgentsHttpError(res.status, body.error ?? body.message ?? res.statusText, body.code, parseBillingPayload(body));
+        throw new AgentsHttpError(res.status, 
+        // `message` FIRST: on a payment_failed envelope it carries the friendly
+        // decline copy ("Your card was declined…") while `error` is the generic
+        // "payment required" — error-first would feed surfaceBillingBlocked the
+        // generic string and lose the decline reason (mirrors outpostRequest).
+        body.message ?? body.error ?? res.statusText, body.code, parseBillingPayload(body));
     }
     return (await res.json());
 }
@@ -371,7 +376,7 @@ export function registerAgentsCommand(program) {
                 if (err instanceof AgentsHttpError &&
                     err.status === 402 &&
                     err.billing) {
-                    await surfaceBillingRequired(token, err.billing);
+                    await surfaceBillingBlocked(token, err.billing, err.message);
                     process.exit(1);
                 }
                 throw err;

package/dist/commands/cloud.d.ts

@@ -22,6 +22,13 @@ import { type BannerLevel } from "../lib/narrow-hint-banner.js";
  * succeed when files were dropped" guarantee unit-testable.
  */
 export declare function scopeExcludedWarning(count: number): string | null;
+/**
+ * Bound foreground waits for a watcher/manual sync that currently owns the
+ * per-root operation lock. The cloud engine reads this environment value on
+ * every lock acquisition. A command-line value wins; otherwise preserve a
+ * valid explicit caller environment value and supply a finite CLI default.
+ */
+export declare function configureSyncLockTimeout(raw: string | undefined): void;
 export interface PullAllVaultClient {
     listMyMemberships(): Promise<Array<{
         companyUid: string;

package/dist/commands/cloud.js

@@ -59,6 +59,21 @@ function resolveDeletePolicy() {
     }
     return "currency-gated";
 }
+const DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS = 300;
+/**
+ * Bound foreground waits for a watcher/manual sync that currently owns the
+ * per-root operation lock. The cloud engine reads this environment value on
+ * every lock acquisition. A command-line value wins; otherwise preserve a
+ * valid explicit caller environment value and supply a finite CLI default.
+ */
+export function configureSyncLockTimeout(raw) {
+    const value = raw ?? process.env.HQ_OP_LOCK_TIMEOUT ?? String(DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS);
+    const seconds = Number(value);
+    if (!Number.isInteger(seconds) || seconds < 0) {
+        throw new Error("--lock-timeout must be a non-negative integer number of seconds");
+    }
+    process.env.HQ_OP_LOCK_TIMEOUT = String(seconds);
+}
 // Oldest-first by createdAt, ties broken by uid lexicographic — matches
 // `pickCanonicalPersonEntity` in @indigoai-us/hq-cloud so the CLI lands on
 // the same person bucket that `hq-sync-runner` picks.
@@ -478,6 +493,7 @@ export function registerCloudCommands(program) {
         .argument("[paths...]", "Paths to push (defaults to current directory)")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .option("--company <slug>", "Company slug or UID (defaults to active company in .hq/config.json)")
+        .option("--lock-timeout <seconds>", "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)")
         .option("--message <msg>", "Optional message attached to journal entries for these uploads")
         .option("--on-conflict <strategy>", "Conflict strategy: overwrite | keep | abort (omit for interactive)")
         .option("--creds-from-stdin", "Read a pre-vended EntityContext as JSON from stdin instead of vending " +
@@ -509,6 +525,7 @@ export function registerCloudCommands(program) {
         "`--all`.")
         .action(async (paths, options) => {
         try {
+            configureSyncLockTimeout(options.lockTimeout);
             assertSingleSelector(options, "push");
         }
         catch (err) {
@@ -688,6 +705,7 @@ export function registerCloudCommands(program) {
         .description("Pull permitted files from the company vault to local HQ")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .option("--company <slug>", "Company slug or UID (defaults to active company in .hq/config.json)")
+        .option("--lock-timeout <seconds>", "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)")
         .option("--on-conflict <strategy>", "Conflict strategy: overwrite | keep | abort (omit for interactive)")
         .option("--all", "Pull every company you are a member of plus your personal vault " +
         "into <hq-root>. Companies land at <hq-root>/companies/<slug>; " +
@@ -711,6 +729,7 @@ export function registerCloudCommands(program) {
         "quarantined under .hq/scope-quarantine/ (recoverable).")
         .action(async (options) => {
         try {
+            configureSyncLockTimeout(options.lockTimeout);
             assertSingleSelector(options, "pull");
         }
         catch (err) {
@@ -882,6 +901,7 @@ export function registerCloudCommands(program) {
         "(mirrors AppBar HQ Sync's \"Sync Now\" button)")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .option("--company <slug>", "Company slug or UID (defaults to active company in .hq/config.json)")
+        .option("--lock-timeout <seconds>", "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)")
         .option("--message <msg>", "Optional message attached to journal entries for the push leg")
         .option("--on-conflict <strategy>", "Conflict strategy: overwrite | keep | abort (omit for interactive)")
         .option("--all", "Sync every company you are a member of plus your personal vault " +
@@ -901,6 +921,7 @@ export function registerCloudCommands(program) {
         "out-of-scope files are quarantined under .hq/scope-quarantine/.")
         .action(async (options) => {
         try {
+            configureSyncLockTimeout(options.lockTimeout);
             assertSingleSelector(options, "now");
             if (options.all) {
                 // `options.personal === false` is Commander's auto-negation

package/dist/commands/files.d.ts

@@ -92,5 +92,66 @@ export declare function stripRedundantCompanyScope(prefix: string): {
 export declare function runFilesDelete(params: RunFilesDeleteParams, deps?: {
     confirm?: ConfirmFn;
 }): Promise<void>;
+export interface FileVersionRow {
+    versionId: string;
+    isLatest: boolean;
+    lastModified: string;
+    size: number;
+    isDeleteMarker?: boolean;
+}
+export interface FilesVersionsResponse {
+    key: string;
+    versions: FileVersionRow[];
+    computedAt: string;
+}
+export interface FileTombstoneRow {
+    key: string;
+    deletedAt: string;
+    deletedBy: string;
+    deletedPrefix: string;
+}
+export interface FilesTrashResponse {
+    companyUid?: string;
+    personal?: true;
+    tombstones: FileTombstoneRow[];
+    cursor?: string | null;
+    truncated: boolean;
+    computedAt: string;
+}
+export interface FilesRestoreResponse {
+    key: string;
+    wasDeleted: boolean;
+    restoredFromVersionId: string;
+    newVersionId: string;
+}
+export declare class FilesRecoveryHttpError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+/** Render the exact-key version history, including S3 delete markers. */
+export declare function formatFilesVersionsTable(rows: FileVersionRow[]): string;
+/** Render durable delete tombstones without implying the objects still exist. */
+export declare function formatFilesTrashTable(rows: FileTombstoneRow[]): string;
+export declare function runFilesVersions(params: {
+    key: string;
+    personal: boolean;
+    companySlug: string | undefined;
+}): Promise<FilesVersionsResponse>;
+export declare function runFilesRestore(params: {
+    key: string;
+    versionId?: string;
+    yes: boolean;
+    personal: boolean;
+    companySlug: string | undefined;
+}, deps?: {
+    confirm?: ConfirmFn;
+}): Promise<FilesRestoreResponse | undefined>;
+export declare function runFilesTrash(params: {
+    prefix: string;
+    cursor?: string;
+    personal: boolean;
+    companySlug: string | undefined;
+}): Promise<FilesTrashResponse>;
 export {};
 //# sourceMappingURL=files.d.ts.map

package/dist/commands/files.js

@@ -379,6 +379,69 @@ export function registerFilesCommand(program) {
             process.exit(1);
         }
     });
+    files
+        .command("versions <path>")
+        .description("List prior content versions and delete markers for one exact vault key. Use --personal for your personal vault.")
+        .option("--personal", "Target your own personal vault instead of a company vault (mutually exclusive with --company)")
+        .action(async (path, opts) => {
+        try {
+            const companySlug = files.opts().company;
+            const personal = opts.personal === true;
+            assertRecoveryScope(personal, companySlug);
+            await runFilesVersions({ key: path, personal, companySlug });
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    files
+        .command("restore <path>")
+        .description("Restore a prior version or undelete an exact vault key. Prompts before overwriting unless --yes. Use --personal for your personal vault.")
+        .option("--personal", "Target your own personal vault instead of a company vault (mutually exclusive with --company)")
+        .option("--version <id>", "Content version ID to restore")
+        .option("-y, --yes", "Skip the overwrite confirmation prompt (for scripts)")
+        .action(async (path, opts) => {
+        try {
+            const companySlug = files.opts().company;
+            const personal = opts.personal === true;
+            assertRecoveryScope(personal, companySlug);
+            await runFilesRestore({
+                key: path,
+                versionId: opts.version,
+                yes: opts.yes === true,
+                personal,
+                companySlug,
+            });
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    files
+        .command("trash")
+        .description("List deleted vault keys retained as tombstones. Use --personal for your personal vault.")
+        .option("--personal", "Target your own personal vault instead of a company vault (mutually exclusive with --company)")
+        .option("--prefix <prefix>", "Literal key prefix to filter tombstones")
+        .option("--cursor <cursor>", "Continue from an opaque tombstone cursor")
+        .action(async (opts) => {
+        try {
+            const companySlug = files.opts().company;
+            const personal = opts.personal === true;
+            assertRecoveryScope(personal, companySlug);
+            await runFilesTrash({
+                prefix: opts.prefix ?? "",
+                cursor: opts.cursor,
+                personal,
+                companySlug,
+            });
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
     // Return the `files` Commander group so callers (src/index.ts) can attach
     // additional subcommands (e.g. `hq files browse`/`hq files cat` from
     // files-browse.ts) onto the same group without re-creating it.
@@ -737,4 +800,215 @@ export async function runFilesDelete(params, deps = {}) {
         console.log(chalk.dim(`${result.skipped} object(s) under this prefix you can't delete were left untouched.`));
     }
 }
+export class FilesRecoveryHttpError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "FilesRecoveryHttpError";
+    }
+}
+function assertRecoveryScope(personal, companySlug) {
+    if (personal && companySlug) {
+        throw new Error("Pass either --personal or --company, not both.");
+    }
+}
+function assertExactRecoveryKey(key) {
+    if (!key || key.includes("*")) {
+        throw new Error("Restore and version history require one exact, wildcard-free vault key.");
+    }
+}
+function quoteRecoveryShellArg(value) {
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return String(bytes) + " B";
+    if (bytes < 1024 * 1024)
+        return (bytes / 1024).toFixed(1) + " KiB";
+    if (bytes < 1024 * 1024 * 1024) {
+        return (bytes / (1024 * 1024)).toFixed(1) + " MiB";
+    }
+    return (bytes / (1024 * 1024 * 1024)).toFixed(1) + " GiB";
+}
+/** Render the exact-key version history, including S3 delete markers. */
+export function formatFilesVersionsTable(rows) {
+    if (rows.length === 0) {
+        return "No version history exists for that key.";
+    }
+    const cols = ["VERSION", "TYPE", "LATEST", "MODIFIED", "SIZE"];
+    const data = rows.map((row) => [
+        row.versionId,
+        row.isDeleteMarker ? "delete marker" : "content",
+        row.isLatest ? "yes" : "",
+        row.lastModified,
+        row.isDeleteMarker ? "—" : formatBytes(row.size),
+    ]);
+    const widths = cols.map((col, index) => Math.max(col.length, ...data.map((row) => row[index].length)));
+    const renderRow = (row) => row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
+    return [
+        chalk.bold(renderRow(cols)),
+        chalk.dim(renderRow(widths.map((width) => "─".repeat(width)))),
+        ...data.map(renderRow),
+    ].join("\n");
+}
+/** Render durable delete tombstones without implying the objects still exist. */
+export function formatFilesTrashTable(rows) {
+    if (rows.length === 0) {
+        return "Trash is empty.";
+    }
+    const cols = ["KEY", "DELETED", "DELETED BY", "DELETE PREFIX"];
+    const data = rows.map((row) => [
+        row.key,
+        row.deletedAt,
+        row.deletedBy,
+        row.deletedPrefix,
+    ]);
+    const widths = cols.map((col, index) => Math.max(col.length, ...data.map((row) => row[index].length)));
+    const renderRow = (row) => row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
+    return [
+        chalk.bold(renderRow(cols)),
+        chalk.dim(renderRow(widths.map((width) => "─".repeat(width)))),
+        ...data.map(renderRow),
+    ].join("\n");
+}
+function throwRecoveryHttpError(status, body, statusText) {
+    throw new FilesRecoveryHttpError(status, body.message ?? body.error ?? statusText, body.code);
+}
+function formatFilesRecoveryError(err, key) {
+    if (err.status === 401) {
+        return "Not authenticated — please run hq login";
+    }
+    if (err.status === 403) {
+        return key
+            ? "Not authorized to modify '" + key + "' — you need write access on it"
+            : "Not authorized to view this vault path";
+    }
+    if (err.code === "FILES_RESTORE_VERSION_NOT_FOUND") {
+        return "That version is unavailable or is a delete marker.";
+    }
+    if (err.code === "FILES_RESTORE_NO_PRIOR_VERSION") {
+        return "There is no prior content version to restore.";
+    }
+    if (err.code === "FILES_RESTORE_NO_RECOVERABLE_VERSION") {
+        return "There is no recoverable content version for this key.";
+    }
+    if (err.status === 400) {
+        return "Invalid request: " + err.message;
+    }
+    if (err.status >= 500) {
+        return "Server error: " + err.message;
+    }
+    return err.message || "Request failed (" + String(err.status) + ")";
+}
+async function resolveRecoveryScope(params) {
+    assertRecoveryScope(params.personal, params.companySlug);
+    const token = await ensureCognitoToken();
+    if (params.personal) {
+        return { token, personal: true };
+    }
+    return {
+        token,
+        personal: false,
+        companyUid: await getCompanyUid(token, params.companySlug),
+    };
+}
+export async function runFilesVersions(params) {
+    assertExactRecoveryKey(params.key);
+    const scope = await resolveRecoveryScope(params);
+    const res = await vaultApiFetch({
+        token: scope.token,
+        path: "/v1/files/versions",
+        query: scope.personal
+            ? { personal: "1", key: params.key }
+            : { company: scope.companyUid, key: params.key },
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throwRecoveryHttpError(res.status, body, res.statusText);
+    }
+    const data = (await res.json());
+    console.log(chalk.green("Versions for '" + data.key + "':"));
+    console.log(formatFilesVersionsTable(data.versions));
+    return data;
+}
+export async function runFilesRestore(params, deps = {}) {
+    assertExactRecoveryKey(params.key);
+    if (params.versionId !== undefined && params.versionId.trim() === "") {
+        throw new Error("versionId must not be empty.");
+    }
+    const confirm = deps.confirm ?? realConfirm;
+    if (!params.yes) {
+        const ok = await confirm(params.personal
+            ? "Restore '" + params.key + "' in your personal vault? This overwrites current content."
+            : "Restore '" + params.key + "'? This overwrites current content in the shared vault.");
+        if (!ok) {
+            console.log(chalk.dim("Aborted — nothing was restored."));
+            return undefined;
+        }
+    }
+    const scope = await resolveRecoveryScope(params);
+    const body = scope.personal
+        ? { personal: true, key: params.key }
+        : { company: scope.companyUid, key: params.key };
+    if (params.versionId !== undefined)
+        body.versionId = params.versionId;
+    const res = await vaultApiFetch({
+        token: scope.token,
+        path: "/v1/files/restore",
+        method: "POST",
+        body,
+    });
+    if (!res.ok) {
+        const errBody = (await res.json().catch(() => ({})));
+        const err = new FilesRecoveryHttpError(res.status, errBody.message ?? errBody.error ?? res.statusText, errBody.code);
+        throw new Error(formatFilesRecoveryError(err, params.key));
+    }
+    const data = (await res.json());
+    const verb = data.wasDeleted ? "Undeleted" : "Restored";
+    console.log(chalk.green(verb + " '" + data.key + "' from version '" + data.restoredFromVersionId + "'."));
+    console.log(chalk.dim("New version: " + data.newVersionId));
+    return data;
+}
+export async function runFilesTrash(params) {
+    if (params.prefix.includes("*")) {
+        throw new Error("Trash prefix must be literal; wildcard expansion is not supported.");
+    }
+    const scope = await resolveRecoveryScope(params);
+    const query = scope.personal
+        ? { personal: "1" }
+        : { company: scope.companyUid };
+    if (params.prefix)
+        query.prefix = params.prefix;
+    if (params.cursor)
+        query.cursor = params.cursor;
+    const res = await vaultApiFetch({
+        token: scope.token,
+        path: "/v1/files/tombstones",
+        query,
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throwRecoveryHttpError(res.status, body, res.statusText);
+    }
+    const data = (await res.json());
+    console.log(formatFilesTrashTable(data.tombstones));
+    if (data.truncated && data.cursor) {
+        let continuation = "hq files";
+        if (params.companySlug) {
+            continuation += " --company " + quoteRecoveryShellArg(params.companySlug);
+        }
+        continuation += " trash";
+        if (params.personal)
+            continuation += " --personal";
+        if (params.prefix) {
+            continuation += " --prefix " + quoteRecoveryShellArg(params.prefix);
+        }
+        continuation += " --cursor " + quoteRecoveryShellArg(data.cursor);
+        console.log(chalk.dim("More results: " + continuation));
+    }
+    return data;
+}
 //# sourceMappingURL=files.js.map

package/dist/commands/outposts.js

@@ -31,7 +31,7 @@ import * as yaml from "js-yaml";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
-import { OUTPOST_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingRequired, } from "../utils/billing-gate.js";
+import { OUTPOST_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Decode hq-pro's `{ capped, limit, outposts }` cap envelope, if present. */
 export function parseCappedPayload(body) {
     if (!body || typeof body !== "object")
@@ -825,7 +825,7 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
                 if (err instanceof OutpostHttpError &&
                     err.status === 402 &&
                     err.billing) {
-                    await surfaceBillingRequired(token, err.billing);
+                    await surfaceBillingBlocked(token, err.billing, err.message);
                     process.exit(1);
                 }
                 // Already at the per-person cap → say so and name the box they own,

package/dist/main.js

@@ -67,6 +67,9 @@ import { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
+import { settleWithin } from "./utils/settle-with-timeout.js";
+/** Hard upper bound for non-user-visible release-health finalization. */
+const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
 // the pipe early. This covers the ASYNC path — an 'error' event emitted on the
 // stream. The SYNCHRONOUS path (a `write EPIPE` thrown straight out of
@@ -306,7 +309,11 @@ export async function runCli() {
     finally {
         // Release health: finalize the per-run session before the flush.
         Sentry.endSession();
-        await Promise.allSettled([refreshVersionCache(), Sentry.flush(2000)]);
+        // Neither task may turn a successful command into Node's
+        // `unsettled top-level await` exit. They are observability-only after the
+        // command has completed, so a bounded best-effort wait is the terminal
+        // lifecycle boundary for this invocation.
+        await settleWithin([refreshVersionCache(), Sentry.flush(2000)], RELEASE_HEALTH_SETTLE_TIMEOUT_MS);
     }
 }
 //# sourceMappingURL=main.js.map

package/dist/utils/billing-gate.d.ts

@@ -74,4 +74,19 @@ export declare function mintPaymentLink(token: string, setup: BillingSetupAction
  * to act on. Never prints tokens or secrets.
  */
 export declare function surfaceBillingRequired(token: string, billing: BillingErrorPayload): Promise<string | null>;
+/**
+ * Status-aware surface for a 402 billing block. hq-pro's envelope carries two
+ * distinct remediations that must never be conflated (mirroring the server's
+ * own P1-C classification):
+ *   - `payment_failed`   — a card EXISTS and the charge was DECLINED. The
+ *     server's `message` already carries the friendly decline copy ("Your
+ *     card was declined…", "insufficient funds", …). Telling this user
+ *     "No card on file" sends them down the wrong remediation path entirely
+ *     (observed live 2026-07-20: a declined $80 Outpost proration surfaced
+ *     as "no card", triggering a hunt for a missing card that existed).
+ *     The capture link still surfaces — as the way to UPDATE the card.
+ *   - anything else (`billing_required`) — genuinely no usable card on
+ *     file; the existing add-a-card copy is correct.
+ */
+export declare function surfaceBillingBlocked(token: string, billing: BillingErrorPayload, serverMessage?: string): Promise<string | null>;
 //# sourceMappingURL=billing-gate.d.ts.map

package/dist/utils/billing-gate.js

@@ -121,4 +121,39 @@ export async function surfaceBillingRequired(token, billing) {
     console.log(chalk.dim("Once a card is added, re-run the same command."));
     return url;
 }
+/**
+ * Status-aware surface for a 402 billing block. hq-pro's envelope carries two
+ * distinct remediations that must never be conflated (mirroring the server's
+ * own P1-C classification):
+ *   - `payment_failed`   — a card EXISTS and the charge was DECLINED. The
+ *     server's `message` already carries the friendly decline copy ("Your
+ *     card was declined…", "insufficient funds", …). Telling this user
+ *     "No card on file" sends them down the wrong remediation path entirely
+ *     (observed live 2026-07-20: a declined $80 Outpost proration surfaced
+ *     as "no card", triggering a hunt for a missing card that existed).
+ *     The capture link still surfaces — as the way to UPDATE the card.
+ *   - anything else (`billing_required`) — genuinely no usable card on
+ *     file; the existing add-a-card copy is correct.
+ */
+export async function surfaceBillingBlocked(token, billing, serverMessage) {
+    if (billing.status !== "payment_failed") {
+        return surfaceBillingRequired(token, billing);
+    }
+    console.error(chalk.yellow(serverMessage?.trim() ||
+        "Your payment failed. Try a different card or contact your bank."));
+    if (!billing.setup)
+        return null;
+    try {
+        const url = await mintPaymentLink(token, billing.setup);
+        console.log("Update or replace the card here (safe to share with whoever owns billing):\n  " +
+            chalk.cyan(url));
+        console.log(chalk.dim("Once the payment method is sorted, re-run the same command."));
+        return url;
+    }
+    catch {
+        // Link minting is best-effort on the decline path — the decline reason
+        // above is the essential part; the console billing page also works.
+        return null;
+    }
+}
 //# sourceMappingURL=billing-gate.js.map

package/dist/utils/settle-with-timeout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Await finalization work without allowing a best-effort promise to leave a
+ * CLI's top-level await pending forever. The timer intentionally stays
+ * referenced: Node must remain alive long enough to settle this race.
+ */
+export declare function settleWithin(promises: readonly Promise<unknown>[], timeoutMs: number): Promise<"settled" | "timed_out">;
+//# sourceMappingURL=settle-with-timeout.d.ts.map

package/dist/utils/settle-with-timeout.js

@@ -0,0 +1,22 @@
+/**
+ * Await finalization work without allowing a best-effort promise to leave a
+ * CLI's top-level await pending forever. The timer intentionally stays
+ * referenced: Node must remain alive long enough to settle this race.
+ */
+export async function settleWithin(promises, timeoutMs) {
+    let timer;
+    const timedOut = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("timed_out"), timeoutMs);
+    });
+    try {
+        return await Promise.race([
+            Promise.allSettled(promises).then(() => "settled"),
+            timedOut,
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=settle-with-timeout.js.map

package/dist/utils/vault-api.js

@@ -176,6 +176,9 @@ async function resolveCompanyUid(token, ref) {
                 `is in your namespace. Re-run with --company <uid> to pick one:\n` +
                 body.uids.map((u) => `  --company ${u}`).join('\n'));
         }
+        if (res.status === 404 && body.error === "Entity not found") {
+            throw Object.assign(new Error(`Company slug '${ref}' was not found. Check the slug or run \`hq companies list\`.`), { expected: true });
+        }
         throw new Error(`Failed to resolve company slug '${ref}': ${body.error ?? res.statusText}`);
     }
     const data = (await res.json());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.76.0",
+  "version": "5.77.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {