@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/run.js

@@ -2,14 +2,16 @@ import { spawn } from 'node:child_process';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { internal } from 'varlock';
-import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { cognitoCachePrincipalUid, ensureCognitoToken } from '../utils/cognito-session.js';
 import { apiKeyCapabilityGateMessage, peekHqApiKey, } from '../utils/resolve-vault-credential.js';
 import { computeSha256 } from '../utils/integrity.js';
+import { isUnavailableSecretLoadHttpStatus, SecretLoadUnavailableError, } from '../utils/secret-load-availability.js';
 import { vaultApiFetch, getCompanyUid } from '../utils/vault-api.js';
 import { discoverSchemas } from '../run/discover-schemas.js';
 import { installHqPlugin, prewarmHqSecrets } from '../run/hq-plugin.js';
 import { assertEnvGraphLoaded, resolveEnvValuesOrThrow, EnvGraphLoadError, EnvResolutionError, } from '../run/env-graph-guard.js';
 import { hadFatalRejection } from '../unhandled-rejection-boundary.js';
+import { withRunSecretReadTelemetry } from './run-feature-telemetry.js';
 const SECRET_LOAD_TIMEOUT_MS = 30_000;
 export async function buildRunUsage(scriptPath, scriptId) {
     if (scriptId && !scriptPath) {
@@ -82,9 +84,11 @@ export function registerRunCommand(program) {
                 throw new Error('company slug not set. Add # @hqCompany("slug") to your .env.schema or pass --company <slug>.');
             }
             const token = await ensureCognitoToken();
-            const uid = await getCompanyUid(token, slug);
+            const uid = await getCompanyUid(token, slug, undefined, {
+                allowOfflineScopeFallback: true,
+            });
             const usage = await buildRunUsage(opts.script, opts.scriptId);
-            const fetchBatch = async (companyUid, names, requestUsage) => {
+            const fetchBatch = async (companyUid, names, requestUsage) => withRunSecretReadTelemetry(companyUid, async () => {
                 const res = await vaultApiFetch({
                     token,
                     path: `/secrets/${encodeURIComponent(companyUid)}/load`,
@@ -99,6 +103,9 @@ export function registerRunCommand(program) {
                         : typeof body.error === 'string'
                             ? body.error
                             : res.statusText;
+                    if (isUnavailableSecretLoadHttpStatus(res.status)) {
+                        throw new SecretLoadUnavailableError(`Failed to batch-load secrets: ${message}`);
+                    }
                     if (res.status >= 400 &&
                         res.status < 500 &&
                         typeof body.code === 'string') {
@@ -107,9 +114,11 @@ export function registerRunCommand(program) {
                     throw new Error(`Failed to batch-load secrets: ${message}`);
                 }
                 return res.json();
-            };
+            });
             const pluginOpts = {
                 companyOverride: opts.company,
+                principalUid: cognitoCachePrincipalUid(token) ?? undefined,
+                allowOfflineFallback: true,
                 resolveCompanyUid: async () => uid,
                 usage,
                 fetchBatch,
@@ -119,6 +128,11 @@ export function registerRunCommand(program) {
             let state;
             const graph = await internal.loadEnvGraph({
                 entryFilePaths: paths,
+                // hq run owns its short-lived in-memory resolution. Varlock's default
+                // cache auto-detection can write ~/.config/varlock and initialize
+                // the native local-encryption helper, neither of which belongs on
+                // this command path.
+                skipCache: true,
                 afterInit: async (g) => { state = installHqPlugin(g, pluginOpts); },
             });
             // Refuse to resolve a graph varlock never finished loading (a malformed

package/dist/commands/safe-extract.d.ts

@@ -32,6 +32,7 @@
  *     actually written (we do NOT rely solely on the pre-flight scan or on the
  *     tar binary's own protections).
  */
+import { execFileSync } from 'child_process';
 export interface ExtractCaps {
     /** Max total uncompressed bytes across all entries. Default 256 MiB. */
     maxUncompressedBytes: number;
@@ -109,9 +110,13 @@ export declare function resolveContainedPath(targetDir: string, entryName: strin
 export declare function assertLinkTargetContained(packDir: string, entryAbs: string, linkTarget: string): void;
 /**
  * List a gzip-compressed tarball's entries via `tar -tvf` (no extraction).
- * argv form — never a shell string — so a hostile filename can't break out.
+ * argv form, never a shell string, keeps hostile filenames out of shell syntax.
+ * Windows drive paths use a basename relative to the archive directory by
+ * default. GNU tar cannot parse `C:\\...` as remote `host:path`, and Windows'
+ * bundled bsdtar accepts the same relative argv without GNU-only `--force-local`.
+ * Callers can still explicitly opt out with `useRelativeWindowsDrivePath: false`.
  */
-export declare function listTarball(tarballPath: string): TarEntry[];
+export declare function listTarball(tarballPath: string, opts?: Pick<SafeExtractOptions, 'platform' | 'useRelativeWindowsDrivePath' | 'execFileSync'>): TarEntry[];
 /**
  * Pre-flight validation against the entry headers. Enforces (a) containment of
  * every entry name under `targetDir`, (b) containment of every link target
@@ -129,6 +134,10 @@ export declare function validateEntries(entries: TarEntry[], targetDir: string,
 export declare function assertExtractContained(stagingDir: string): void;
 export interface SafeExtractOptions {
     caps?: ExtractCaps;
+    /** Test seams for platform-specific argv construction; runtime gating uses hq-flags. */
+    platform?: NodeJS.Platform;
+    useRelativeWindowsDrivePath?: boolean;
+    execFileSync?: typeof execFileSync;
     /**
      * Test seam: invoked AFTER `tar` extracts into the staging dir but BEFORE
      * the post-extract sweep / atomic rename. Throwing here simulates a failure

package/dist/commands/safe-extract.js

@@ -203,18 +203,34 @@ export function assertLinkTargetContained(packDir, entryAbs, linkTarget) {
             `"${linkTarget}" -> "${resolvedTarget}", outside pack dir "${path.resolve(packDir)}".`);
     }
 }
-// ---------------------------------------------------------------------------
-// Pre-flight: list entries, enforce containment + caps WITHOUT extracting
-// ---------------------------------------------------------------------------
+function tarballArgvLocation(tarballPath, platform, useRelativeWindowsDrivePath) {
+    if (platform === 'win32' &&
+        useRelativeWindowsDrivePath &&
+        /^[A-Za-z]:[\\/]/.test(tarballPath)) {
+        return {
+            archiveArg: path.win32.basename(tarballPath),
+            cwd: path.win32.dirname(tarballPath),
+        };
+    }
+    return { archiveArg: tarballPath };
+}
 /**
  * List a gzip-compressed tarball's entries via `tar -tvf` (no extraction).
- * argv form — never a shell string — so a hostile filename can't break out.
+ * argv form, never a shell string, keeps hostile filenames out of shell syntax.
+ * Windows drive paths use a basename relative to the archive directory by
+ * default. GNU tar cannot parse `C:\\...` as remote `host:path`, and Windows'
+ * bundled bsdtar accepts the same relative argv without GNU-only `--force-local`.
+ * Callers can still explicitly opt out with `useRelativeWindowsDrivePath: false`.
  */
-export function listTarball(tarballPath) {
-    const out = execFileSync('tar', ['-tvf', tarballPath], {
+export function listTarball(tarballPath, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const useRelativeWindowsDrivePath = opts.useRelativeWindowsDrivePath ?? true;
+    const location = tarballArgvLocation(tarballPath, platform, useRelativeWindowsDrivePath);
+    const out = (opts.execFileSync ?? execFileSync)('tar', ['-tvf', location.archiveArg], {
         encoding: 'utf-8',
         maxBuffer: 64 * 1024 * 1024,
         stdio: ['ignore', 'pipe', 'pipe'],
+        ...(location.cwd ? { cwd: location.cwd } : {}),
     });
     return parseTarListing(out);
 }
@@ -311,8 +327,17 @@ export function safeExtractTarball(tarballPath, finalDir, opts = {}) {
     if (fs.existsSync(finalDir)) {
         throw new Error(`safeExtractTarball: refusing to extract over existing dir "${finalDir}".`);
     }
+    // Resolve once so listing and extraction use the same archive location.
+    const platform = opts.platform ?? process.platform;
+    const useRelativeWindowsDrivePath = opts.useRelativeWindowsDrivePath ?? true;
+    const exec = opts.execFileSync ?? execFileSync;
+    const location = tarballArgvLocation(tarballPath, platform, useRelativeWindowsDrivePath);
     // 1. Pre-flight against headers (no bytes written yet).
-    const entries = listTarball(tarballPath);
+    const entries = listTarball(tarballPath, {
+        platform,
+        useRelativeWindowsDrivePath,
+        execFileSync: exec,
+    });
     validateEntries(entries, finalDir, caps);
     // 2. Sibling staging dir on the same filesystem so the rename is atomic.
     const parent = path.dirname(path.resolve(finalDir));
@@ -322,7 +347,10 @@ export function safeExtractTarball(tarballPath, finalDir, opts = {}) {
         // `--no-same-owner` avoids chown surprises when run as root; argv form, no
         // shell. We deliberately re-extract here (not the pre-flight listing) and
         // re-validate after, rather than trusting tar to honor any single flag.
-        execFileSync('tar', ['-xzf', tarballPath, '-C', stagingDir, '--no-same-owner'], { stdio: 'inherit' });
+        exec('tar', ['-xzf', location.archiveArg, '-C', stagingDir, '--no-same-owner'], {
+            stdio: 'inherit',
+            ...(location.cwd ? { cwd: location.cwd } : {}),
+        });
         // 3. Independent backstop sweep over what actually landed.
         assertExtractContained(stagingDir);
         // 4. Failure-injection seam (tests).

package/dist/commands/secrets.d.ts

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import type { Command } from "commander";
 import { writeSync } from "node:fs";
 import { vaultApiFetch, getCompanyUid, getEntityUid } from "../utils/vault-api.js";
 export type { VaultApiOptions } from "../utils/vault-api.js";
@@ -31,6 +31,7 @@ export interface SecretMetadata {
         requiredAttestation?: string;
     };
     cacheTtlMs?: number;
+    revokedAt?: string | null;
 }
 export interface SecretLoadSuccessRow extends SecretMetadata {
     name: string;
@@ -59,7 +60,9 @@ export declare function parseDestinationUrl(raw: string): {
 };
 export declare function collectSecretNames(value: string, previous?: string[]): string[];
 export declare function scrubSandboxOutput(text: string, secretNames?: string[]): string;
-export declare function loadRevealedSecrets(token: string, companyUid: string, keys: string[], usage?: SecretUsage): Promise<Map<string, string>>;
+export declare function loadRevealedSecrets(token: string, companyUid: string, keys: string[], usage?: SecretUsage, options?: {
+    allowOfflineFallback?: boolean;
+}): Promise<Map<string, string>>;
 /**
  * Emit `hq secrets env` output and terminate deterministically.
  *
@@ -85,5 +88,20 @@ export declare function loadRevealedSecrets(token: string, companyUid: string, k
  * `exit` and `write` are injectable for tests; production uses the real ones.
  */
 export declare function emitEnvExportsAndExit(payload: string, exit?: (code: number) => never, write?: typeof writeSync): never;
+/**
+ * Shared `secrets env` action for Commander and the default-off lightweight
+ * entrypoint. The fast entrypoint still runs the same credential, usage-audit,
+ * server authorization, cache-fallback, redaction, and output code.
+ */
+export declare function runSecretsEnvCommand(opts: {
+    only: string[];
+    script?: string;
+    scriptId?: string;
+}, parentScope: {
+    company?: string;
+    personal?: boolean;
+}, options?: {
+    fallbackOnAuthFailure?: boolean;
+}): Promise<"handled" | "fallback">;
 export declare function registerSecretsCommand(program: Command): void;
 //# sourceMappingURL=secrets.d.ts.map

package/dist/commands/secrets.js

@@ -1,16 +1,16 @@
 import chalk from "chalk";
-import * as readline from "node:readline";
-import { spawn } from "node:child_process";
 import { writeSync } from "node:fs";
 import * as nodePath from "node:path";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { cognitoCachePrincipalUid, ensureCognitoToken } from "../utils/cognito-session.js";
+import { isAuthError } from "../utils/auth-error.js";
 import { DEFAULT_SECRETS_CACHE_TTL_MS, hasCacheEntry, readCache, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
 import { computeSha256 } from "../utils/integrity.js";
+import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
 import { vaultApiFetch, getCompanyUid, getEntityUid, looksLikeCompanyUid, } from "../utils/vault-api.js";
 import { HQ_API_KEY_PREFIX, formatApiKeyCapabilityDenial, requireApiKeyCapability, resolveVaultCredentialForCapability, } from "../utils/resolve-vault-credential.js";
-import { SandboxRunnerClient, } from "../utils/sandbox-runner-client.js";
+import { CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE, isSecretLoadUnavailable, isUnavailableSecretLoadHttpStatus, SecretLoadUnavailableError, } from "../utils/secret-load-availability.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
 /**
  * Mirrors `RESOURCE_SURFACES` in hq-pro
@@ -43,7 +43,19 @@ export const CLI_SECRETS_SET_SURFACE = "cli_secrets_set";
  */
 async function requireCognitoTokenForSecrets(commandLabel, capability = null) {
     requireApiKeyCapability(capability, commandLabel, { routeAvailable: false });
-    return ensureCognitoToken();
+    return ensureCognitoToken(secretsCredentialOptions());
+}
+/**
+ * A browser login is safe only when a person can answer it. This mirrors the
+ * repository's existing terminal convention in `canOfferTeamUpgrade`: both
+ * stdin and stderr must be TTYs, and CI is always non-interactive.
+ */
+function secretsCredentialOptions() {
+    return {
+        interactive: process.stdin.isTTY === true &&
+            process.stderr.isTTY === true &&
+            !process.env.CI,
+    };
 }
 function scopeOpts(opts) {
     if (opts.personal && opts.company) {
@@ -96,7 +108,7 @@ function resolveApiKeyCompanyUid(scope, commandLabel) {
     return ref;
 }
 async function resolveSecretsTarget(capability, commandLabel, scopeOptions) {
-    const cred = await resolveVaultCredentialForCapability(capability, commandLabel);
+    const cred = await resolveVaultCredentialForCapability(capability, commandLabel, secretsCredentialOptions());
     const scope = scopeOpts(scopeOptions);
     const isApiKey = cred.kind === "api-key";
     const companyUid = isApiKey
@@ -145,14 +157,16 @@ function parseDuration(input) {
     return null;
 }
 function confirmPrompt(message) {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-    return new Promise((resolve) => {
-        rl.question(`${message} [y/N] `, (answer) => {
-            rl.close();
-            resolve(answer.trim().toLowerCase() === "y");
+    return import("node:readline").then(({ createInterface }) => {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        return new Promise((resolve) => {
+            rl.question(`${message} [y/N] `, (answer) => {
+                rl.close();
+                resolve(answer.trim().toLowerCase() === "y");
+            });
         });
     });
 }
@@ -176,12 +190,23 @@ function promptSecretInteractively() {
         let value = "";
         process.stdin.setEncoding("utf8");
         const cleanup = () => {
-            if (process.stdin.isTTY) {
-                process.stdin.setRawMode(false);
+            try {
+                if (process.stdin.isTTY) {
+                    try {
+                        process.stdin.setRawMode(false);
+                    }
+                    catch (error) {
+                        if (error?.code !== "EBADF") {
+                            throw error;
+                        }
+                    }
+                }
+            }
+            finally {
+                process.stdin.removeListener("data", onData);
+                process.stdin.removeListener("end", onEnd);
+                process.stdin.pause();
             }
-            process.stdin.removeListener("data", onData);
-            process.stdin.removeListener("end", onEnd);
-            process.stdin.pause();
         };
         const onEnd = () => {
             cleanup();
@@ -510,11 +535,11 @@ function renderPolicyScripts(scripts) {
 // `env` through it stops those callers from emitting the warning while keeping
 // identical UX and error text.
 //
-// Every value use through exec/env/reveal is server-authorized, including when
-// an encrypted disk-cache entry exists. The cache remains write-through for
-// explicitly offline install-time consumers; these commands never trust it as
-// an authorization decision. This means a policy, ACL, tier, or script-approval
-// change takes effect on their next use even though there is no push revocation.
+// Every value use through exec/env/reveal is server-authorized when online,
+// including when an encrypted disk-cache entry exists. Only explicitly opted-in
+// exec/env callers may use principal-bound values during classified outages;
+// install authorization and reveal remain online-only. This means a policy,
+// ACL, tier, or script-approval change takes effect on the next online use.
 // Requests are chunked at MAX_BATCH_NAMES and throw on the FIRST unresolved key
 // with the same `Failed to fetch secret '<k>': <reason>` shape the per-key GET
 // path used — never swallows a failure.
@@ -562,13 +587,16 @@ async function loadRevealedSecretsViaApiKey(token, keys) {
     }
     return resolved;
 }
-export async function loadRevealedSecrets(token, companyUid, keys, usage) {
+export async function loadRevealedSecrets(token, companyUid, keys, usage, options = {}) {
     if (token.startsWith(HQ_API_KEY_PREFIX)) {
         return loadRevealedSecretsViaApiKey(token, keys);
     }
     const resolved = new Map();
     const requested = [...new Set(keys)];
-    const cachedCandidates = new Set(requested.filter((name) => hasCacheEntry(companyUid, name)));
+    const principalUid = cognitoCachePrincipalUid(token);
+    const cachedCandidates = new Set(principalUid
+        ? requested.filter((name) => hasCacheEntry(companyUid, name, principalUid))
+        : []);
     try {
         // The batch endpoint is the only non-capturing authorization path that also
         // evaluates the supplied usage metadata. It covers warm and cold names in
@@ -595,6 +623,9 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
                     body.highSecurity === true) {
                     throw new Error(highSecuritySandboxOnlyMessage());
                 }
+                if (isUnavailableSecretLoadHttpStatus(res.status)) {
+                    throw new SecretLoadUnavailableError(`Failed to batch-load secrets: ${message}`);
+                }
                 if (res.status >= 400 &&
                     res.status < 500 &&
                     typeof body.code === "string") {
@@ -623,6 +654,14 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
                     throw new Error("Invalid secret load response from vault");
                 }
                 seenNames.add(s.name);
+                if (s.revokedAt != null) {
+                    errorsByName.set(s.name, {
+                        code: "revoked",
+                        message: `Secret '${s.name}' has been revoked`,
+                    });
+                    removeCacheEntry(companyUid, s.name);
+                    continue;
+                }
                 if (s.value == null) {
                     errorsByName.set(s.name, {
                         code: "not_returned",
@@ -637,7 +676,7 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
                     typeof s.version === "number" &&
                     Number.isSafeInteger(s.version) &&
                     s.version > 0
-                    ? readCache(companyUid, s.name, s.version, cacheTtlMs)
+                    ? readCache(companyUid, s.name, principalUid, s.version, cacheTtlMs)
                     : null;
                 if (cached !== null) {
                     resolved.set(s.name, cached);
@@ -647,10 +686,12 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
                     if (typeof s.version === "number" &&
                         Number.isSafeInteger(s.version) &&
                         s.version > 0) {
-                        writeCache(companyUid, s.name, s.value, cacheTtlMs, s.version);
+                        if (principalUid) {
+                            writeCache(companyUid, s.name, principalUid, s.value, cacheTtlMs, s.version);
+                        }
                     }
-                    else {
-                        writeCache(companyUid, s.name, s.value, cacheTtlMs);
+                    else if (principalUid) {
+                        writeCache(companyUid, s.name, principalUid, s.value, cacheTtlMs);
                     }
                 }
                 else {
@@ -707,9 +748,29 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
         return resolved;
     }
     catch (err) {
+        if (isSecretLoadUnavailable(err) && options.allowOfflineFallback === true) {
+            const offline = new Map();
+            for (const key of requested) {
+                const cached = cachedCandidates.has(key)
+                    ? readCache(companyUid, key, principalUid)
+                    : null;
+                if (cached === null) {
+                    // Keep the same failure behavior for a cache miss, while leaving any
+                    // still-valid entries untouched for a later retry.
+                    throw err;
+                }
+                offline.set(key, cached);
+            }
+            console.error(CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE);
+            return offline;
+        }
+        if (isSecretLoadUnavailable(err)) {
+            throw err;
+        }
         // A transport failure, stale session, malformed response, or a later chunk
-        // failure must not leave values written by this attempted operation available
-        // to offline cache readers. Evict the whole request before failing closed.
+        // failure is an explicit denial or unusable response. Evict the whole
+        // request before failing closed. Transient no-answer/5xx/429 failures above
+        // preserve entries and only use values still valid under their stored TTL.
         for (const key of requested) {
             removeCacheEntry(companyUid, key);
         }
@@ -760,6 +821,61 @@ export function emitEnvExportsAndExit(payload, exit = process.exit, write = writ
     }
     return exit(0);
 }
+/**
+ * Shared `secrets env` action for Commander and the default-off lightweight
+ * entrypoint. The fast entrypoint still runs the same credential, usage-audit,
+ * server authorization, cache-fallback, redaction, and output code.
+ */
+export async function runSecretsEnvCommand(opts, parentScope, options = {}) {
+    let secretLoadStarted = false;
+    try {
+        const redact = process.stdout.isTTY;
+        if (redact) {
+            console.error(chalk.yellow("stdout is a terminal — values redacted. Use: source <(hq secrets env --only KEY1,KEY2)"));
+        }
+        const keys = parseSecretNameList(opts.only);
+        const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets env", secretsCredentialOptions());
+        const companyUid = cred.kind === "api-key"
+            ? "__api_key__"
+            : await getEntityUid(cred.token, scopeOpts(parentScope), {
+                allowOfflineScopeFallback: true,
+            });
+        const usage = cred.kind === "cognito"
+            ? await buildSecretUsage("env", opts.script, opts.scriptId)
+            : undefined;
+        secretLoadStarted = true;
+        const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, usage, { allowOfflineFallback: true });
+        let payload = "";
+        for (const key of keys) {
+            const value = revealed.get(key);
+            // loadRevealedSecrets throws on any unresolved key, so a miss here is
+            // unreachable — guard rather than print an `undefined` export line.
+            if (value === undefined) {
+                throw new Error(`Failed to fetch secret '${key}': not returned by vault`);
+            }
+            const out = redact ? "[REDACTED]" : value;
+            payload += `export ${key}=${shellSingleQuote(out)}\n`;
+        }
+        // Write synchronously and exit unconditionally — never depend on the
+        // event loop draining or the stdout write callback firing. See
+        // emitEnvExportsAndExit for the full rationale (orphaned-process leak).
+        emitEnvExportsAndExit(payload);
+        return "handled";
+    }
+    catch (err) {
+        if (options.fallbackOnAuthFailure &&
+            !secretLoadStarted &&
+            (isAuthError(err) ||
+                (err instanceof Error &&
+                    (/^No valid HQ session\b/.test(err.message) ||
+                        /^HQ_API_KEY must start with /.test(err.message))))) {
+            return "fallback";
+        }
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+        return "handled";
+    }
+}
 export function registerSecretsCommand(program) {
     const secrets = program
         .command("secrets")
@@ -873,6 +989,11 @@ export function registerSecretsCommand(program) {
             }
         }
         catch (err) {
+            // A plan-limit refusal goes to main.ts's shared renderer, which prints
+            // the reason, usage, fix options and upgrade link, offers the upgrade
+            // interactively, and exits non-zero.
+            if (isPlanGateError(err))
+                throw err;
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
             process.exit(1);
         }
@@ -883,7 +1004,7 @@ export function registerSecretsCommand(program) {
         .option("--reveal", "Include the decrypted secret value")
         .action(async (name, opts) => {
         try {
-            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets get");
+            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets get", secretsCredentialOptions());
             if (cred.kind === "api-key") {
                 if (!opts.reveal) {
                     console.error(chalk.red("HQ_API_KEY is set; `hq secrets get` without --reveal is not supported for API keys. " +
@@ -956,7 +1077,7 @@ export function registerSecretsCommand(program) {
             let revealError = null;
             if (opts.reveal) {
                 try {
-                    revealedValue = (await loadRevealedSecrets(token, companyUid, [name], await buildSecretUsage("reveal"))).get(name);
+                    revealedValue = (await loadRevealedSecrets(token, companyUid, [name], await buildSecretUsage("reveal"), { allowOfflineFallback: false })).get(name);
                 }
                 catch (err) {
                     revealError = err instanceof Error ? err.message : String(err);
@@ -1384,6 +1505,7 @@ export function registerSecretsCommand(program) {
             const token = await requireCognitoTokenForSecrets("secrets sandbox", "secrets:read");
             const scope = scopeOpts(mergeScopeOpts(secrets.opts(), opts));
             const companyUid = await getEntityUid(token, scope);
+            const { SandboxRunnerClient } = await import("../utils/sandbox-runner-client.js");
             const client = new SandboxRunnerClient();
             const started = await client.startJob(token, {
                 companyUid,
@@ -1434,13 +1556,23 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const keys = parseSecretNameList(_opts.only);
-            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets exec");
+            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets exec", secretsCredentialOptions());
             const companyUid = cred.kind === "api-key"
                 ? "__api_key__"
-                : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
-            const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
+                : await getEntityUid(cred.token, scopeOpts(secrets.opts()), { allowOfflineScopeFallback: true });
+            const readSecrets = async () => loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
                 ? await buildSecretUsage("exec", _opts.script, _opts.scriptId)
-                : undefined);
+                : undefined, { allowOfflineFallback: true });
+            // API-key auth has no signed-in person identity for the CLI telemetry
+            // endpoint. Do not attribute that read to an unrelated cached session.
+            let revealed;
+            if (cred.kind === "cognito") {
+                const { withCliFeatureUsed } = await import("../utils/cli-telemetry.js");
+                revealed = await withCliFeatureUsed("secret_read", readSecrets, companyUid);
+            }
+            else {
+                revealed = await readSecrets();
+            }
             const secretEnv = {};
             for (const key of keys) {
                 const value = revealed.get(key);
@@ -1452,6 +1584,7 @@ export function registerSecretsCommand(program) {
                 secretEnv[key] = value;
             }
             const [childCmd, ...childCmdArgs] = childArgs;
+            const { spawn } = await import("node:child_process");
             const child = spawn(childCmd, childCmdArgs, {
                 stdio: "inherit",
                 env: { ...process.env, ...secretEnv },
@@ -1479,39 +1612,7 @@ export function registerSecretsCommand(program) {
         .option("--script <path>", "Attach local script identity for script-locked secrets")
         .option("--script-id <id>", "Stable script identifier approved by policy")
         .action(async (opts) => {
-        try {
-            const redact = process.stdout.isTTY;
-            if (redact) {
-                console.error(chalk.yellow("stdout is a terminal — values redacted. Use: source <(hq secrets env --only KEY1,KEY2)"));
-            }
-            const keys = parseSecretNameList(opts.only);
-            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets env");
-            const companyUid = cred.kind === "api-key"
-                ? "__api_key__"
-                : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
-            const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
-                ? await buildSecretUsage("env", opts.script, opts.scriptId)
-                : undefined);
-            let payload = "";
-            for (const key of keys) {
-                const value = revealed.get(key);
-                // loadRevealedSecrets throws on any unresolved key, so a miss here is
-                // unreachable — guard rather than print an `undefined` export line.
-                if (value === undefined) {
-                    throw new Error(`Failed to fetch secret '${key}': not returned by vault`);
-                }
-                const out = redact ? "[REDACTED]" : value;
-                payload += `export ${key}=${shellSingleQuote(out)}\n`;
-            }
-            // Write synchronously and exit unconditionally — never depend on the
-            // event loop draining or the stdout write callback firing. See
-            // emitEnvExportsAndExit for the full rationale (orphaned-process leak).
-            emitEnvExportsAndExit(payload);
-        }
-        catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
+        await runSecretsEnvCommand(opts, secrets.opts());
     });
     secrets
         .command("generate-link <name>")
@@ -1555,6 +1656,9 @@ export function registerSecretsCommand(program) {
             console.log(chalk.dim("  One-time use — link is invalidated after first submission."));
         }
         catch (err) {
+            // Same shared plan-limit renderer as `secrets set` (see main.ts).
+            if (isPlanGateError(err))
+                throw err;
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
             process.exit(1);
         }