@indigoai-us/hq-cli 5.75.0 → 5.77.0

package/dist/run/hq-plugin.js

@@ -1,9 +1,19 @@
 import { ResolutionError } from 'varlock/plugin-lib';
-import { DEFAULT_SECRETS_CACHE_TTL_MS, readCache, writeCache, } from '../utils/secrets-cache.js';
-function normalizeCacheTtlMs(cacheTtlMs) {
-    return typeof cacheTtlMs === 'number'
-        ? cacheTtlMs
-        : DEFAULT_SECRETS_CACHE_TTL_MS;
+import { DEFAULT_SECRETS_CACHE_TTL_MS, writeCache, removeCacheEntry, } from '../utils/secrets-cache.js';
+function normalizeCacheTtlMs(secret) {
+    if (secret.tier === 'sensitive' ||
+        secret.tier === 'nuclear' ||
+        secret.scriptLock?.mode === 'enforced') {
+        return 0;
+    }
+    if (secret.cacheTtlMs === undefined) {
+        return DEFAULT_SECRETS_CACHE_TTL_MS;
+    }
+    return typeof secret.cacheTtlMs === 'number' &&
+        Number.isFinite(secret.cacheTtlMs) &&
+        secret.cacheTtlMs > 0
+        ? secret.cacheTtlMs
+        : 0;
 }
 export function installHqPlugin(graph /* EnvGraph */, opts) {
     const pluginState = {
@@ -41,9 +51,9 @@ export function installHqPlugin(graph /* EnvGraph */, opts) {
             impliesSensitive: true,
             argsSchema: { type: 'array', arrayMaxLength: 1 },
             resolve: async function () {
-                // Cache-only read. `pluginState` is captured by this inner-class closure;
-                // `prewarmHqSecrets(graph, opts, state)` populates `state.uid` and
-                // `state.errorsByName` before `graph.resolveEnvValues()` calls us.
+                // `pluginState` is captured by this inner-class closure;
+                // `prewarmHqSecrets(graph, opts, state)` server-authorizes and populates
+                // the in-memory values before `graph.resolveEnvValues()` calls us.
                 const explicit = this.arrArgs?.[0]?.staticValue;
                 const secretName = (typeof explicit === 'string' && explicit) ? explicit : this._ownerKey;
                 if (!secretName) {
@@ -66,11 +76,6 @@ export function installHqPlugin(graph /* EnvGraph */, opts) {
                     }
                     throw new ResolutionError(`Failed to load secret "${secretName}": ${err.message ?? err.code}`);
                 }
-                // Sentinel-check style throughout: `readCache` returns `string | null`
-                // (verified at `hq/packages/hq-cli/src/utils/secrets-cache.ts:45`); `pluginState.uid`
-                // is `string | null` per `PluginState`. Use `== null` (covers null AND undefined defensively)
-                // for both — do not mix in truthy checks like `if (!x)`, which would silently swallow a
-                // legitimate empty-string value if the contract ever loosened.
                 if (pluginState.uid == null) {
                     throw new ResolutionError('Internal error: prewarmHqSecrets was not called before resolveEnvValues');
                 }
@@ -78,11 +83,7 @@ export function installHqPlugin(graph /* EnvGraph */, opts) {
                 if (inMemory != null) {
                     return inMemory;
                 }
-                const cached = readCache(pluginState.uid, secretName); // string | null
-                if (cached == null) {
-                    throw new ResolutionError(`Internal error: pre-warm did not populate cache for "${secretName}"`);
-                }
-                return cached;
+                throw new ResolutionError(`Secret "${secretName}" was not returned by vault after server authorization`);
             },
         };
         // Captured during process(parent); used by resolve() to fall back to the var key.
@@ -144,22 +145,84 @@ export async function prewarmHqSecrets(graph /* EnvGraph */, opts, state) {
     if (uniqueNames.length > 100) {
         throw new Error(`hq run supports at most 100 hq() resolvers per schema; got ${uniqueNames.length}`);
     }
-    const result = await opts.fetchBatch(uid, uniqueNames, opts.usage);
-    for (const s of result.secrets) {
-        if (s.value == null) {
-            continue;
+    state.loadedSecretsByName.clear();
+    state.errorsByName = new Map();
+    let result;
+    try {
+        result = await opts.fetchBatch(uid, uniqueNames, opts.usage);
+        if (!Array.isArray(result.secrets) || !Array.isArray(result.errors)) {
+            throw new Error('Invalid secret load response from vault');
         }
-        state.loadedSecretsByName.set(s.name, s.value);
-        const cacheTtlMs = normalizeCacheTtlMs(s.cacheTtlMs);
-        if (cacheTtlMs > 0) {
-            writeCache(uid, s.name, s.value, cacheTtlMs);
+        const errorsByName = new Map();
+        const returnedNames = new Set();
+        const requestedNames = new Set(uniqueNames);
+        const seenNames = new Set();
+        for (const rawSecret of result.secrets) {
+            if (!rawSecret || typeof rawSecret !== 'object') {
+                throw new Error('Invalid secret load response from vault');
+            }
+            const s = rawSecret;
+            if (typeof s.name !== 'string' ||
+                !requestedNames.has(s.name) ||
+                seenNames.has(s.name) ||
+                (s.value != null && typeof s.value !== 'string')) {
+                throw new Error('Invalid secret load response from vault');
+            }
+            seenNames.add(s.name);
+            if (s.value == null) {
+                errorsByName.set(s.name, {
+                    code: 'not_returned',
+                    message: 'not returned by vault after server authorization',
+                });
+                removeCacheEntry(uid, s.name);
+                continue;
+            }
+            returnedNames.add(s.name);
+            state.loadedSecretsByName.set(s.name, s.value);
+            const cacheTtlMs = normalizeCacheTtlMs(s);
+            if (cacheTtlMs > 0) {
+                writeCache(uid, s.name, s.value, cacheTtlMs);
+            }
+            else {
+                removeCacheEntry(uid, s.name);
+            }
+        }
+        for (const rawError of result.errors) {
+            if (!rawError || typeof rawError !== 'object') {
+                throw new Error('Invalid secret load response from vault');
+            }
+            const e = rawError;
+            if (typeof e.name !== 'string' ||
+                !requestedNames.has(e.name) ||
+                seenNames.has(e.name) ||
+                typeof e.code !== 'string' ||
+                (e.message !== undefined && typeof e.message !== 'string')) {
+                throw new Error('Invalid secret load response from vault');
+            }
+            seenNames.add(e.name);
+            errorsByName.set(e.name, { code: e.code, message: e.message });
+            state.loadedSecretsByName.delete(e.name);
+            removeCacheEntry(uid, e.name);
         }
+        for (const name of uniqueNames) {
+            if (!returnedNames.has(name) && !errorsByName.has(name)) {
+                errorsByName.set(name, {
+                    code: 'not_returned',
+                    message: 'not returned by vault after server authorization',
+                });
+                removeCacheEntry(uid, name);
+            }
+        }
+        state.errorsByName = errorsByName;
+        state.uid = uid;
     }
-    const errorsByName = new Map();
-    for (const e of result.errors) {
-        errorsByName.set(e.name, { code: e.code, message: e.message });
+    catch (err) {
+        state.loadedSecretsByName.clear();
+        state.errorsByName = new Map();
+        for (const name of uniqueNames) {
+            removeCacheEntry(uid, name);
+        }
+        throw err;
     }
-    state.errorsByName = errorsByName;
-    state.uid = uid;
 }
 //# sourceMappingURL=hq-plugin.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/sandbox-runner-client.d.ts

@@ -12,6 +12,7 @@ export interface SandboxRunnerJob {
     jobId: string;
     status: SandboxRunnerState;
     output?: string;
+    error?: string;
     exitCode?: number;
     success?: boolean;
 }

package/dist/utils/sandbox-runner-client.js

@@ -36,6 +36,7 @@ function normalizeJob(body, jobIdFallback) {
             : jobIdFallback ?? requireString(body, "jobId"),
         status,
         output: typeof body.output === "string" ? body.output : undefined,
+        error: typeof body.error === "string" ? body.error : undefined,
         exitCode: typeof body.exitCode === "number" ? body.exitCode : undefined,
         success: typeof body.success === "boolean" ? body.success : undefined,
     };

package/dist/utils/secrets-cache.d.ts

@@ -3,11 +3,10 @@ export declare function readCache(companyUid: string, name: string): string | nu
 export declare function writeCache(companyUid: string, name: string, value: string, ttlMs?: number): void;
 /**
  * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
- * secrets-cache directory on disk. Used by offline callers (e.g. install-time MCP
- * registration) that have no `--company` flag and no network token and so cannot
- * resolve a single active company UID up front: they instead probe every cached
- * scope for a given secret name. Returns `[]` when the cache root is absent or
- * unreadable (the desired graceful-deferral behavior — no scopes, no hits).
+ * secrets-cache directory on disk. Install-time MCP registration may use an
+ * exactly-one result as a scope hint before reauthorizing every value online; it
+ * never reads cached plaintext through this helper. Returns `[]` when the cache
+ * root is absent or unreadable.
  */
 export declare function listSecretCacheScopes(): string[];
 export declare function removeCacheEntry(companyUid: string, name: string): void;

package/dist/utils/secrets-cache.js

@@ -140,11 +140,10 @@ export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACH
 }
 /**
  * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
- * secrets-cache directory on disk. Used by offline callers (e.g. install-time MCP
- * registration) that have no `--company` flag and no network token and so cannot
- * resolve a single active company UID up front: they instead probe every cached
- * scope for a given secret name. Returns `[]` when the cache root is absent or
- * unreadable (the desired graceful-deferral behavior — no scopes, no hits).
+ * secrets-cache directory on disk. Install-time MCP registration may use an
+ * exactly-one result as a scope hint before reauthorizing every value online; it
+ * never reads cached plaintext through this helper. Returns `[]` when the cache
+ * root is absent or unreadable.
  */
 export function listSecretCacheScopes() {
     try {
@@ -152,9 +151,7 @@ export function listSecretCacheScopes() {
             .readdirSync(CACHE_DIR, { withFileTypes: true })
             .filter((e) => e.isDirectory())
             .map((e) => e.name)
-            // Only real entity scopes (cmp_*/prs_*); validateInputs in readCache also
-            // rejects anything with `/` or `..`, so this is belt-and-suspenders.
-            .filter((name) => !name.startsWith("."));
+            .filter((name) => /^(?:cmp|prs)_[A-Za-z0-9_-]+$/.test(name));
     }
     catch {
         return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.75.0",
+  "version": "5.77.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -11,6 +11,7 @@
     "build": "node scripts/generate-dsn.mjs && tsc && node scripts/chmod-bins.mjs",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit",
+    "gen:scan-golden": "node scripts/generate-scan-packages-table.mjs > src/utils/__fixtures__/scan-packages.generated-block.sh",
     "lint": "eslint .",
     "test": "vitest run",
     "test:db": "vitest run src/lib/db test/commands/db.test.ts test/commands/db-tenant-isolation.test.ts",
@@ -21,7 +22,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "^6.14.4",
+    "@indigoai-us/hq-cloud": "^6.14.14",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "better-sqlite3": "^12.11.1",

package/pnpm-workspace.yaml

@@ -1,2 +1,4 @@
 allowBuilds:
   better-sqlite3: true
+minimumReleaseAgeExclude:
+  - '@indigoai-us/hq-cloud@6.14.14'

package/src/commands/agents.test.ts

@@ -363,6 +363,47 @@ describe("hq agents provision (billing gate)", () => {
     expect(printed).toContain("https://checkout.stripe.com/card");
   });
 
+  it("surfaces the DECLINE reason on 402 payment_failed (message-first decoding)", async () => {
+    // The payment_failed envelope carries BOTH the generic error AND the
+    // friendly decline message — the decode must prefer `message` or the
+    // decline copy is lost and the operator sees "add a card" for a card
+    // that exists and was declined.
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(402, {
+          error: "payment required",
+          message:
+            "Your card was declined. Try a different card or contact your bank.",
+          code: "PAYMENT_FAILED",
+          billing: {
+            status: "payment_failed",
+            setup: {
+              payerType: "company",
+              path: "/v1/billing/checkout/org",
+              method: "POST",
+              body: { companyUid: "cmp_acme" },
+            },
+          },
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, { url: "https://checkout.stripe.com/update" }),
+      );
+
+    const logSpyLocal = vi.spyOn(console, "log").mockImplementation(() => {});
+    const errSpyLocal = vi.spyOn(console, "error").mockImplementation(() => {});
+    await expect(
+      run(["agents", "--company", "acme", "provision", "Ops Bot", "--yes"]),
+    ).rejects.toThrow("process.exit(1)");
+
+    const printed = [...errSpyLocal.mock.calls, ...logSpyLocal.mock.calls]
+      .map((c) => c.map(String).join(" "))
+      .join("\n");
+    expect(printed).toContain("declined");
+    expect(printed).not.toContain("No card on file");
+    expect(printed).toContain("https://checkout.stripe.com/update");
+  });
+
   it("requires --api-key-env for --auth-mode apiKey (before any charge)", async () => {
     await expect(
       run([

package/src/commands/agents.ts

@@ -31,7 +31,7 @@ import {
   AGENT_PRICE_CENTS,
   confirmChargeOrExit,
   parseBillingPayload,
-  surfaceBillingRequired,
+  surfaceBillingBlocked,
   type BillingErrorPayload,
 } from "../utils/billing-gate.js";
 
@@ -125,7 +125,11 @@ export async function agentsRequest<T>(opts: {
     };
     throw new AgentsHttpError(
       res.status,
-      body.error ?? body.message ?? res.statusText,
+      // `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),
     );
@@ -592,7 +596,7 @@ export function registerAgentsCommand(program: Command): void {
             err.status === 402 &&
             err.billing
           ) {
-            await surfaceBillingRequired(token, err.billing);
+            await surfaceBillingBlocked(token, err.billing, err.message);
             process.exit(1);
           }
           throw err;