@indigoai-us/hq-cli 5.75.0 → 5.77.0

package/src/run/hq-plugin.ts

@@ -2,15 +2,27 @@ import { ResolutionError } from 'varlock/plugin-lib';
 import type { Resolver } from 'varlock/plugin-lib';
 import {
   DEFAULT_SECRETS_CACHE_TTL_MS,
-  readCache,
   writeCache,
+  removeCacheEntry,
 } from '../utils/secrets-cache.js';
 import type { SecretLoadResponse, SecretUsage } from '../commands/secrets.js';
 
-function normalizeCacheTtlMs(cacheTtlMs?: number): number {
-  return typeof cacheTtlMs === 'number'
-    ? cacheTtlMs
-    : DEFAULT_SECRETS_CACHE_TTL_MS;
+function normalizeCacheTtlMs(secret: SecretLoadResponse['secrets'][number]): number {
+  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 interface InstallHqPluginOpts {
@@ -69,9 +81,9 @@ export function installHqPlugin(graph: any /* EnvGraph */, opts: InstallHqPlugin
       impliesSensitive: true,
       argsSchema: { type: 'array' as const, arrayMaxLength: 1 },
       resolve: async function (this: HqResolver) {
-        // 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) {
@@ -94,11 +106,6 @@ export function installHqPlugin(graph: any /* EnvGraph */, opts: InstallHqPlugin
           }
           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');
         }
@@ -106,11 +113,9 @@ export function installHqPlugin(graph: any /* EnvGraph */, opts: InstallHqPlugin
         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`,
+        );
       },
     };
 
@@ -186,22 +191,87 @@ export async function prewarmHqSecrets(
       `hq run supports at most 100 hq() resolvers per schema; got ${uniqueNames.length}`,
     );
   }
-  const result = await opts.fetchBatch(uid, uniqueNames, opts.usage);
+  state.loadedSecretsByName.clear();
+  state.errorsByName = new Map();
+
+  let result: SecretLoadResponse;
+  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');
+    }
 
-  for (const s of result.secrets) {
-    if (s.value == null) {
-      continue;
+    const errorsByName = new Map<string, { code: string; message?: string }>();
+    const returnedNames = new Set<string>();
+    const requestedNames = new Set(uniqueNames);
+    const seenNames = new Set<string>();
+    for (const rawSecret of result.secrets) {
+      if (!rawSecret || typeof rawSecret !== 'object') {
+        throw new Error('Invalid secret load response from vault');
+      }
+      const s = rawSecret as SecretLoadResponse['secrets'][number];
+      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 as { name?: unknown; code?: unknown; message?: unknown };
+      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.loadedSecretsByName.set(s.name, s.value);
-    const cacheTtlMs = normalizeCacheTtlMs(s.cacheTtlMs);
-    if (cacheTtlMs > 0) {
-      writeCache(uid, s.name, s.value, cacheTtlMs);
+    state.errorsByName = errorsByName;
+    state.uid = uid;
+  } catch (err) {
+    state.loadedSecretsByName.clear();
+    state.errorsByName = new Map();
+    for (const name of uniqueNames) {
+      removeCacheEntry(uid, name);
     }
+    throw err;
   }
-  const errorsByName = new Map<string, { code: string; message?: string }>();
-  for (const e of result.errors) {
-    errorsByName.set(e.name, { code: e.code, message: e.message });
-  }
-  state.errorsByName = errorsByName;
-  state.uid = uid;
 }

package/src/utils/__fixtures__/scan-packages.generated-block.sh

@@ -0,0 +1,23 @@
+# >>> BEGIN GENERATED contribution table (US-003) — do not edit by hand
+# Generated from hq-cli/src/utils/contribution-table.ts by
+# hq-cli/scripts/generate-scan-packages-table.mjs. Regenerate with:
+#   node scripts/generate-scan-packages-table.mjs --write core/scripts/scan-packages.sh
+# Each row is "payload|host|wire" (payload uses {item} for the name).
+# bash 3.2-compatible (macOS default bash has no associative arrays):
+# a plain indexed key list + a generated case-lookup function.
+CONTRIB_KEYS=(workers knowledge skills commands hooks policies scripts mcp)
+# contrib_row <key> -> echoes "payload|host|wire", empty if unknown.
+contrib_row() {
+  case "$1" in
+    workers) printf '%s' 'workers/{item}|core/workers/public|symlink' ;;
+    knowledge) printf '%s' 'knowledge/{item}|core/knowledge/public|symlink' ;;
+    skills) printf '%s' 'skills/{item}|.claude/skills|symlink' ;;
+    commands) printf '%s' 'commands/{item}.md|.claude/commands|symlink' ;;
+    hooks) printf '%s' 'hooks/{item}.sh|.claude/hooks|symlink' ;;
+    policies) printf '%s' 'policies/{item}.md|core/policies|symlink' ;;
+    scripts) printf '%s' 'scripts/{item}|core/scripts|symlink' ;;
+    mcp) printf '%s' 'mcp/{item}.json|merge:claude+codex|merge' ;;
+    *) return 0 ;;
+  esac
+}
+# <<< END GENERATED contribution table

package/src/utils/billing-gate.ts

@@ -180,3 +180,49 @@ export async function surfaceBillingRequired(
   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: string,
+  billing: BillingErrorPayload,
+  serverMessage?: string,
+): Promise<string | null> {
+  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;
+  }
+}

package/src/utils/pack-contributions.test.ts

@@ -12,6 +12,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { fileURLToPath } from 'node:url';
 import {
   contributionLinks,
   linkStatus,
@@ -102,12 +103,28 @@ describe('contributionLinks: mapping', () => {
 // the WRONG payload suffix, or the WRONG wire mode.
 // ---------------------------------------------------------------------------
 describe('US-003 parity: contribution table is the single source', () => {
-  // Resolve the HQ root so we can read the GENERATED scan-packages.sh block.
-  const scanCandidates = [
-    path.resolve(process.cwd(), '../../../core/scripts/scan-packages.sh'),
-    path.resolve(process.cwd(), '../../../../core/scripts/scan-packages.sh'),
-  ];
-  const scanPath = scanCandidates.find((p) => fs.existsSync(p));
+  // The bash block that `core/scripts/scan-packages.sh` reads is GENERATED from
+  // the contribution table (scripts/generate-scan-packages-table.mjs) and lives
+  // in hq-core — a separately-versioned repo this package never contains. We
+  // vendor that generated block as a committed golden fixture and compare the
+  // table against it, so this guard runs DETERMINISTICALLY in CI and from any
+  // checkout. Regenerate after any table change: `pnpm gen:scan-golden`
+  // (hq-core's own scan-packages.sh must be regenerated from the same table —
+  // that cross-repo leg is enforced in the monorepo that holds both).
+  //
+  // Anchored to THIS module via import.meta.url — never process.cwd().
+  // REGRESSION (do NOT reintroduce): the old resolver did
+  //   path.resolve(process.cwd(), '../../../core/scripts/scan-packages.sh')
+  // which, from a checkout sitting 3 levels below an installed HQ (e.g.
+  // HQ/workspace/worktrees/<name>), bound to that unrelated, differently-
+  // versioned hq-core script and false-failed; from anywhere else it resolved
+  // outside the repo and silently skipped, so the guard NEVER ran — not even in
+  // CI. See the module-anchor regression test below.
+  const goldenBlockPath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    '__fixtures__',
+    'scan-packages.generated-block.sh',
+  );
 
   // Parse the generated `contrib_row` case arms back into {key:{payload,host,wire}}.
   function parseBashTable(bash: string): Record<
@@ -173,31 +190,73 @@ describe('US-003 parity: contribution table is the single source', () => {
     expect(suffix(CONTRIBUTION_TABLE.scripts.payload)).toBe('');
   });
 
-  (scanPath ? it : it.skip)(
-    'scan-packages.sh generated block matches the table on key-set + payload + host + wire',
-    () => {
-      const bash = fs.readFileSync(scanPath as string, 'utf-8');
-      const bashTable = parseBashTable(bash);
-
-      // FULL key-set equivalence (fails if a surface is MISSING a key or has an
-      // EXTRA one — not just a substring presence check).
-      expect(Object.keys(bashTable).sort()).toEqual([...CONTRIBUTION_KEYS].sort());
-
-      // Per-key payload + host + wire-mode equivalence.
-      for (const k of CONTRIBUTION_KEYS) {
-        expect(bashTable[k], `scan-packages.sh missing row for "${k}"`).toBeDefined();
-        expect(bashTable[k].payload).toBe(CONTRIBUTION_TABLE[k].payload);
-        expect(bashTable[k].host).toBe(CONTRIBUTION_TABLE[k].host);
-        expect(bashTable[k].wire).toBe(CONTRIBUTION_TABLE[k].wire);
-      }
-
-      // The CONTRIB_KEYS array in the script also lists every key.
-      const keysLine = bash.match(/CONTRIB_KEYS=\(([^)]*)\)/);
-      expect(keysLine).not.toBeNull();
-      const bashKeys = (keysLine as RegExpMatchArray)[1].trim().split(/\s+/).sort();
-      expect(bashKeys).toEqual([...CONTRIBUTION_KEYS].sort());
-    },
-  );
+  it('generated block (vendored golden) matches the table on key-set + payload + host + wire', () => {
+    const bash = fs.readFileSync(goldenBlockPath, 'utf-8');
+    const bashTable = parseBashTable(bash);
+
+    // FULL key-set equivalence (fails if the golden is MISSING a key or has an
+    // EXTRA one — not just a substring presence check). This doubles as the
+    // drift guard: if the table changed but the golden wasn't regenerated, one
+    // of these assertions fails with the exact key/field that diverged.
+    expect(Object.keys(bashTable).sort()).toEqual([...CONTRIBUTION_KEYS].sort());
+
+    // Per-key payload + host + wire-mode equivalence.
+    for (const k of CONTRIBUTION_KEYS) {
+      expect(
+        bashTable[k],
+        `golden block missing row for "${k}" — run \`pnpm gen:scan-golden\``,
+      ).toBeDefined();
+      expect(bashTable[k].payload).toBe(CONTRIBUTION_TABLE[k].payload);
+      expect(bashTable[k].host).toBe(CONTRIBUTION_TABLE[k].host);
+      expect(bashTable[k].wire).toBe(CONTRIBUTION_TABLE[k].wire);
+    }
+
+    // The CONTRIB_KEYS array in the block also lists every key.
+    const keysLine = bash.match(/CONTRIB_KEYS=\(([^)]*)\)/);
+    expect(keysLine).not.toBeNull();
+    const bashKeys = (keysLine as RegExpMatchArray)[1].trim().split(/\s+/).sort();
+    expect(bashKeys).toEqual([...CONTRIBUTION_KEYS].sort());
+  });
+
+  it('resolves the golden from the module, never from process.cwd() (regression: a co-located HQ must not bind)', () => {
+    // Rebuild the exact historical trap: an installed-HQ-shaped dir carrying a
+    // DIFFERENT scan-packages.sh, with a checkout nested 3 levels below it
+    // (the HQ/workspace/worktrees/<name> layout that first surfaced this bug).
+    const fakeHq = mkTmp('fake-hq-');
+    fs.mkdirSync(path.join(fakeHq, 'core', 'scripts'), { recursive: true });
+    fs.writeFileSync(
+      path.join(fakeHq, 'core', 'scripts', 'scan-packages.sh'),
+      '# unrelated, differently-versioned hq-core script\n',
+    );
+    const nested = path.join(fakeHq, 'workspace', 'worktrees', 'hq-cli-x');
+    fs.mkdirSync(nested, { recursive: true });
+
+    const orig = process.cwd();
+    try {
+      process.chdir(nested);
+      // Module-anchored resolution is unaffected by cwd and points at the repo
+      // golden — which really exists and is what the parity test reads.
+      expect(fs.existsSync(goldenBlockPath)).toBe(true);
+      expect(
+        goldenBlockPath.endsWith(
+          path.join('src', 'utils', '__fixtures__', 'scan-packages.generated-block.sh'),
+        ),
+      ).toBe(true);
+      // The OLD cwd-relative resolver WOULD have latched onto the fake file.
+      // Prove the trap is real, and that we no longer resolve to it.
+      const oldCwdRelative = path.resolve(
+        process.cwd(),
+        '../../../core/scripts/scan-packages.sh',
+      );
+      expect(oldCwdRelative).toBe(
+        path.join(fakeHq, 'core', 'scripts', 'scan-packages.sh'),
+      );
+      expect(oldCwdRelative).not.toBe(goldenBlockPath);
+    } finally {
+      process.chdir(orig);
+      fs.rmSync(fakeHq, { recursive: true, force: true });
+    }
+  });
 
   it('validateManifest payload reader (payloadFor) agrees with the table for every key', () => {
     for (const k of CONTRIBUTION_KEYS) {

package/src/utils/sandbox-runner-client.test.ts

@@ -225,12 +225,39 @@ describe("SandboxRunnerClient", () => {
     ).resolves.toMatchObject({
       jobId: "job_1",
       status: "failed",
+      error: undefined,
       output: "boom\n",
       exitCode: 2,
       success: false,
     });
   });
 
+  // The wire shape the server actually sends when it could not RUN the command:
+  // a reason, and no exit code, because nothing ever exited.
+  it("surfaces the reason on a job the sandbox could not execute", async () => {
+    const fetchImpl = vi.fn<typeof fetch>(async () =>
+      jsonRes({
+        jobId: "job_1",
+        status: "failed",
+        error: "Sandbox max-exec exceeded (28000ms)",
+      }),
+    );
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+    });
+
+    await expect(
+      client.pollJob("jwt-token", "job_1", { intervalMs: 0 }),
+    ).resolves.toMatchObject({
+      jobId: "job_1",
+      status: "failed",
+      error: "Sandbox max-exec exceeded (28000ms)",
+      exitCode: undefined,
+      output: undefined,
+    });
+  });
+
   it("uses the requested job id when the live status response omits it", async () => {
     const fetchImpl = vi.fn<typeof fetch>(async () =>
       jsonRes({ status: "succeeded", output: "ok\n" }),
@@ -244,6 +271,7 @@ describe("SandboxRunnerClient", () => {
       jobId: "job_live",
       status: "succeeded",
       output: "ok\n",
+      error: undefined,
       exitCode: undefined,
       success: undefined,
     });

package/src/utils/sandbox-runner-client.ts

@@ -15,6 +15,7 @@ export interface SandboxRunnerJob {
   jobId: string;
   status: SandboxRunnerState;
   output?: string;
+  error?: string;
   exitCode?: number;
   success?: boolean;
 }
@@ -88,6 +89,7 @@ function normalizeJob(
         : 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/src/utils/secrets-cache.ts

@@ -144,11 +144,10 @@ export function writeCache(
 
 /**
  * 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(): string[] {
   try {
@@ -156,9 +155,7 @@ export function listSecretCacheScopes(): string[] {
       .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/test/commands/signals.test.ts

@@ -55,7 +55,7 @@ let restoreFetch: (() => void) | undefined;
 let tmpHqRoot: string;
 let savedEnv: { HQ_ACCESS_TOKEN: string | undefined };
 
-beforeEach(() => {
+beforeEach(async () => {
   savedEnv = { HQ_ACCESS_TOKEN: process.env.HQ_ACCESS_TOKEN };
   process.env.HQ_ACCESS_TOKEN = "test-access-token";
 
@@ -73,7 +73,7 @@ beforeEach(() => {
 
   // `files` serves the fixture over the presigned-URL transport (the path
   // company reads take).
-  restoreFetch = mockVaultService({
+  restoreFetch = await mockVaultService({
     entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
     files: [
       {

package/test/commands/sources.test.ts

@@ -62,7 +62,7 @@ let restoreFetch: (() => void) | undefined;
 let tmpHqRoot: string;
 let savedEnv: { HQ_ACCESS_TOKEN: string | undefined };
 
-beforeEach(() => {
+beforeEach(async () => {
   // Sidestep Cognito interactive flow.
   savedEnv = { HQ_ACCESS_TOKEN: process.env.HQ_ACCESS_TOKEN };
   process.env.HQ_ACCESS_TOKEN = "test-access-token";
@@ -83,7 +83,7 @@ beforeEach(() => {
 
   // Default vault-service mock with one entity 'indigo'. `files` serves the
   // fixture over the presigned-URL transport (the path company reads take).
-  restoreFetch = mockVaultService({
+  restoreFetch = await mockVaultService({
     entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
     files: [
       {