@indigoai-us/hq-cli 5.255.0 → 5.256.0

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.256.0] — 2026-09-28
+
 ## [5.255.0] — 2026-09-28
 
 ### Changed
@@ -26,6 +28,7 @@
 - `hq db sql --remote` is hidden because remote SQL is not available in this
   CLI build. Existing scripts get a clear error, and local SQL remains
   available without `--remote`.
+- `hq secrets` and `hq run` now use cached secrets during a temporary server outage, up to each secret’s configured cache lifetime. The default is three hours; revoked and high-security secrets still fail closed.
 
 ## [5.253.0] — 2026-09-27
 

package/dist/commands/integrations-import.js

@@ -350,7 +350,9 @@ export function registerImportCommands(integrations) {
         }
         const secretNames = [...Object.values({ ...(manifest.env ?? {}), ...(manifest.headers ?? {}) }), ...(manifest.args ?? [])]
             .flatMap((value) => [...value.matchAll(/\$\{secret:([A-Z][A-Z0-9_]*(?:\/[A-Z][A-Z0-9_]*)*)\}/g)].map((match) => match[1]));
-        const secrets = await loadRevealedSecrets(token, companyUid, secretNames);
+        const secrets = await loadRevealedSecrets(token, companyUid, secretNames, undefined, {
+            allowOfflineFallback: false,
+        });
         const result = registerServer({
             name: safeName,
             manifest,

package/dist/commands/pack-install.js

@@ -1421,7 +1421,9 @@ export async function makeInstallSecretResolver(secretNames, company) {
                 return () => null;
             [scopeUid] = scopes;
         }
-        const authorized = await loadRevealedSecrets(token, scopeUid, names);
+        const authorized = await loadRevealedSecrets(token, scopeUid, names, undefined, {
+            allowOfflineFallback: false,
+        });
         return (name) => authorized.get(name) ?? null;
     }
     catch {

package/dist/commands/run.js

@@ -2,9 +2,10 @@ 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';
@@ -82,7 +83,9 @@ 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 res = await vaultApiFetch({
@@ -99,6 +102,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') {
@@ -110,6 +116,8 @@ export function registerRunCommand(program) {
             };
             const pluginOpts = {
                 companyOverride: opts.company,
+                principalUid: cognitoCachePrincipalUid(token) ?? undefined,
+                allowOfflineFallback: true,
                 resolveCompanyUid: async () => uid,
                 usage,
                 fetchBatch,

package/dist/commands/secrets.d.ts

@@ -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.
  *

package/dist/commands/secrets.js

@@ -3,13 +3,14 @@ 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 { DEFAULT_SECRETS_CACHE_TTL_MS, hasCacheEntry, readCache, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
 import { computeSha256 } from "../utils/integrity.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 { CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE, isSecretLoadUnavailable, isUnavailableSecretLoadHttpStatus, SecretLoadUnavailableError, } from "../utils/secret-load-availability.js";
 import { SandboxRunnerClient, } from "../utils/sandbox-runner-client.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
 /**
@@ -533,11 +534,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.
@@ -585,13 +586,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
@@ -618,6 +622,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") {
@@ -646,6 +653,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",
@@ -660,7 +675,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);
@@ -670,10 +685,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 {
@@ -730,9 +747,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);
         }
@@ -979,7 +1016,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);
@@ -1460,10 +1497,10 @@ export function registerSecretsCommand(program) {
             const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets exec", secretsCredentialOptions());
             const companyUid = cred.kind === "api-key"
                 ? "__api_key__"
-                : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
+                : await getEntityUid(cred.token, scopeOpts(secrets.opts()), { allowOfflineScopeFallback: true });
             const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
                 ? await buildSecretUsage("exec", _opts.script, _opts.scriptId)
-                : undefined);
+                : undefined, { allowOfflineFallback: true });
             const secretEnv = {};
             for (const key of keys) {
                 const value = revealed.get(key);
@@ -1511,10 +1548,10 @@ export function registerSecretsCommand(program) {
             const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets env", secretsCredentialOptions());
             const companyUid = cred.kind === "api-key"
                 ? "__api_key__"
-                : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
+                : await getEntityUid(cred.token, scopeOpts(secrets.opts()), { allowOfflineScopeFallback: true });
             const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
                 ? await buildSecretUsage("env", opts.script, opts.scriptId)
-                : undefined);
+                : undefined, { allowOfflineFallback: true });
             let payload = "";
             for (const key of keys) {
                 const value = revealed.get(key);

package/dist/run/hq-plugin.d.ts

@@ -1,6 +1,10 @@
 import type { SecretLoadResponse, SecretUsage } from '../commands/secrets.js';
 export interface InstallHqPluginOpts {
     companyOverride?: string;
+    /** Local cache identity derived from the current Cognito person/agent token. */
+    principalUid?: string;
+    /** Only hq run opts into encrypted offline values. */
+    allowOfflineFallback?: boolean;
     resolveCompanyUid: (slug: string) => Promise<string>;
     usage?: SecretUsage;
     fetchBatch: (uid: string, names: string[], usage?: SecretUsage) => Promise<SecretLoadResponse>;

package/dist/run/hq-plugin.js

@@ -1,5 +1,6 @@
 import { ResolutionError } from 'varlock/plugin-lib';
-import { DEFAULT_SECRETS_CACHE_TTL_MS, writeCache, removeCacheEntry, } from '../utils/secrets-cache.js';
+import { DEFAULT_SECRETS_CACHE_TTL_MS, hasCacheEntry, readCache, writeCache, removeCacheEntry, } from '../utils/secrets-cache.js';
+import { CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE, isSecretLoadUnavailable, } from '../utils/secret-load-availability.js';
 function normalizeCacheTtlMs(secret) {
     if (secret.tier === 'sensitive' ||
         secret.tier === 'nuclear' ||
@@ -169,6 +170,14 @@ export async function prewarmHqSecrets(graph /* EnvGraph */, opts, state) {
                 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(uid, s.name);
+                continue;
+            }
             if (s.value == null) {
                 errorsByName.set(s.name, {
                     code: 'not_returned',
@@ -180,8 +189,8 @@ export async function prewarmHqSecrets(graph /* EnvGraph */, opts, state) {
             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, s.version);
+            if (cacheTtlMs > 0 && opts.principalUid) {
+                writeCache(uid, s.name, opts.principalUid, s.value, cacheTtlMs, s.version);
             }
             else {
                 removeCacheEntry(uid, s.name);
@@ -219,6 +228,24 @@ export async function prewarmHqSecrets(graph /* EnvGraph */, opts, state) {
     catch (err) {
         state.loadedSecretsByName.clear();
         state.errorsByName = new Map();
+        if (isSecretLoadUnavailable(err) && opts.allowOfflineFallback === true && opts.principalUid) {
+            const cached = new Map();
+            for (const name of uniqueNames) {
+                const value = hasCacheEntry(uid, name, opts.principalUid)
+                    ? readCache(uid, name, opts.principalUid)
+                    : null;
+                if (value === null) {
+                    throw err;
+                }
+                cached.set(name, value);
+            }
+            state.loadedSecretsByName = cached;
+            state.uid = uid;
+            console.error(CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE);
+            return;
+        }
+        if (isSecretLoadUnavailable(err))
+            throw err;
         for (const name of uniqueNames) {
             removeCacheEntry(uid, name);
         }

package/dist/utils/cognito-session.d.ts

@@ -173,6 +173,8 @@ export declare function cognitoSubjectFromToken(token: string | undefined): {
     sub: string | null;
     entityUid: string | null;
 };
+/** Stable local cache identity for a Cognito person or agent principal. */
+export declare function cognitoCachePrincipalUid(token: string | undefined): string | null;
 /** Stable subject key. Null when neither sub nor entity uid is present. */
 export declare function cognitoSubjectKey(tokens: {
     idToken?: string;

package/dist/utils/cognito-session.js

@@ -434,6 +434,11 @@ export function cognitoSubjectFromToken(token) {
     const entityUid = typeof entity === "string" && entity.length > 0 ? entity : null;
     return { sub, entityUid };
 }
+/** Stable local cache identity for a Cognito person or agent principal. */
+export function cognitoCachePrincipalUid(token) {
+    const claims = cognitoSubjectFromToken(token);
+    return claims.entityUid ?? claims.sub;
+}
 /** Stable subject key. Null when neither sub nor entity uid is present. */
 export function cognitoSubjectKey(tokens) {
     if (!tokens)

package/dist/utils/secret-load-availability.d.ts

@@ -0,0 +1,8 @@
+export declare class SecretLoadUnavailableError extends Error {
+    readonly serverUnavailable = true;
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function isUnavailableSecretLoadHttpStatus(status: number): boolean;
+export declare function isSecretLoadUnavailable(err: unknown): boolean;
+export declare const CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE = "using cached secrets; server unavailable";
+//# sourceMappingURL=secret-load-availability.d.ts.map

package/dist/utils/secret-load-availability.js

@@ -0,0 +1,54 @@
+export class SecretLoadUnavailableError extends Error {
+    serverUnavailable = true;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "SecretLoadUnavailableError";
+    }
+}
+const TRANSIENT_NETWORK_CODES = new Set([
+    "ECONNABORTED",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "EPIPE",
+    "UND_ERR_ABORTED",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+export function isUnavailableSecretLoadHttpStatus(status) {
+    return status === 408 || status === 429 || (status >= 500 && status <= 599);
+}
+export function isSecretLoadUnavailable(err) {
+    if (err instanceof SecretLoadUnavailableError)
+        return true;
+    const seen = new Set();
+    let current = err;
+    for (let depth = 0; depth < 4 && current && !seen.has(current); depth += 1) {
+        seen.add(current);
+        if (typeof current !== "object")
+            break;
+        const record = current;
+        if (typeof record.code === "string" &&
+            TRANSIENT_NETWORK_CODES.has(record.code)) {
+            return true;
+        }
+        if (record.name === "TimeoutError" || record.name === "AbortError") {
+            return true;
+        }
+        if (record instanceof TypeError &&
+            typeof record.message === "string" &&
+            /fetch failed|network error/i.test(record.message)) {
+            return true;
+        }
+        current = record.cause;
+    }
+    return false;
+}
+export const CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE = "using cached secrets; server unavailable";
+//# sourceMappingURL=secret-load-availability.js.map

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

@@ -1,12 +1,16 @@
 export declare const DEFAULT_SECRETS_CACHE_TTL_MS: number;
-export declare function readCache(companyUid: string, name: string, expectedVersion?: number, maxAgeMs?: number): string | null;
+export declare function readCache(companyUid: string, name: string, principalUid: string, expectedVersion?: number, maxAgeMs?: number): string | null;
 /**
  * Returns whether an unexpired entry exists without decrypting its plaintext.
  * Callers use this only to decide whether to reauthorize a possible cache hit;
  * they must complete that authorization before calling {@link readCache}.
  */
-export declare function hasCacheEntry(companyUid: string, name: string): boolean;
-export declare function writeCache(companyUid: string, name: string, value: string, ttlMs?: number, version?: number): void;
+export declare function hasCacheEntry(companyUid: string, name: string, principalUid: string): boolean;
+export declare function writeCache(companyUid: string, name: string, principalUid: string, value: string, ttlMs?: number, version?: number): void;
+/** Persist the last successfully resolved scope for a principal, encrypted and authenticated. */
+export declare function writeCachedScopeUid(scopeKey: string, principalUid: string, scopeUid: string): void;
+/** Return a still-valid scope UID only for the principal that wrote it. */
+export declare function readCachedScopeUid(scopeKey: string, principalUid: string): string | null;
 /**
  * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
  * secrets-cache directory on disk. Install-time MCP registration may use an

package/dist/utils/secrets-cache.js

@@ -6,9 +6,11 @@ const CACHE_DIR = path.join(os.homedir(), ".hq", "secrets-cache");
 const KEY_PATH = path.join(CACHE_DIR, ".key");
 const CACHE_FORMAT_MAGIC = Buffer.from("HQSC");
 const CACHE_FORMAT_MAGIC_BYTES = CACHE_FORMAT_MAGIC.length;
-const CACHE_VERSION_MARKER = Buffer.from("HQSCV2\0");
+const CACHE_VERSION_MARKER = Buffer.from("HQSCV3\0");
+const PREVIOUS_CACHE_VERSION_MARKER = Buffer.from("HQSCV2\0");
 const LEGACY_CACHE_VERSION_MARKER = Buffer.from("HQSCV1\0");
 const CACHE_VERSION_MARKER_BYTES = CACHE_VERSION_MARKER.length;
+const PRINCIPAL_DIGEST_BYTES = 32;
 const LEGACY_TIMESTAMP_BYTES = 8;
 const TIMESTAMP_BYTES = 8;
 const TTL_BYTES = 8;
@@ -16,7 +18,9 @@ const CACHE_VERSION_BYTES = 8;
 const ALGORITHM = "aes-256-gcm";
 const IV_BYTES = 12;
 const AUTH_TAG_BYTES = 16;
-export const DEFAULT_SECRETS_CACHE_TTL_MS = 5 * 60 * 1000;
+const SCOPE_CACHE_MAGIC = Buffer.from("HQSSV1\0");
+const SCOPE_KEY_DIR = "scopes";
+export const DEFAULT_SECRETS_CACHE_TTL_MS = 3 * 60 * 60 * 1000;
 function ensureCacheDir(companyUid) {
     const dir = path.join(CACHE_DIR, companyUid);
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -58,7 +62,10 @@ function readCacheVersion(raw, offset) {
         return undefined;
     return isCacheVersion(value) ? value : null;
 }
-function cacheAad(header, companyUid, name) {
+function principalDigest(principalUid) {
+    return crypto.createHash("sha256").update(principalUid, "utf8").digest();
+}
+function cacheAad(header, companyUid, name, principalUid) {
     const company = Buffer.from(companyUid, "utf8");
     const secretName = Buffer.from(name, "utf8");
     const companyLength = Buffer.alloc(4);
@@ -72,6 +79,7 @@ function cacheAad(header, companyUid, name) {
         company,
         nameLength,
         secretName,
+        principalDigest(principalUid),
     ]);
 }
 function parseCacheHeader(raw) {
@@ -82,8 +90,9 @@ function parseCacheHeader(raw) {
         let ivStart = baseHeaderBytes;
         let version;
         let identityAuthenticated = false;
+        let encodedPrincipalDigest;
         if (raw.length >=
-            baseHeaderBytes + CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
+            baseHeaderBytes + CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES + PRINCIPAL_DIGEST_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
             raw
                 .subarray(baseHeaderBytes, baseHeaderBytes + CACHE_VERSION_MARKER_BYTES)
                 .equals(CACHE_VERSION_MARKER)) {
@@ -91,9 +100,22 @@ function parseCacheHeader(raw) {
             if (parsedVersion === null)
                 return null;
             version = parsedVersion;
-            ivStart += CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES;
+            const principalStart = baseHeaderBytes + CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES;
+            encodedPrincipalDigest = raw.subarray(principalStart, principalStart + PRINCIPAL_DIGEST_BYTES);
+            ivStart += CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES + PRINCIPAL_DIGEST_BYTES;
             identityAuthenticated = true;
         }
+        else if (raw.length >=
+            baseHeaderBytes + PREVIOUS_CACHE_VERSION_MARKER.length + CACHE_VERSION_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
+            raw
+                .subarray(baseHeaderBytes, baseHeaderBytes + PREVIOUS_CACHE_VERSION_MARKER.length)
+                .equals(PREVIOUS_CACHE_VERSION_MARKER)) {
+            const parsedVersion = readCacheVersion(raw, baseHeaderBytes + PREVIOUS_CACHE_VERSION_MARKER.length);
+            if (parsedVersion === null)
+                return null;
+            version = parsedVersion;
+            ivStart += PREVIOUS_CACHE_VERSION_MARKER.length + CACHE_VERSION_BYTES;
+        }
         else if (raw.length >=
             baseHeaderBytes + LEGACY_CACHE_VERSION_MARKER.length + CACHE_VERSION_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
             raw
@@ -114,6 +136,7 @@ function parseCacheHeader(raw) {
             ttlMs: Number(raw.readBigInt64BE(CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES)),
             version,
             identityAuthenticated,
+            principalDigest: encodedPrincipalDigest,
             ivStart,
             authTagStart,
             ciphertextStart,
@@ -136,8 +159,8 @@ function isExpired(header, maxAgeMs) {
     const ageMs = Date.now() - header.timestampMs;
     return !Number.isFinite(ttlMs) || ttlMs <= 0 || ageMs < 0 || ageMs > ttlMs;
 }
-export function readCache(companyUid, name, expectedVersion, maxAgeMs) {
-    if (!validateInputs(companyUid, name))
+export function readCache(companyUid, name, principalUid, expectedVersion, maxAgeMs) {
+    if (!validateInputs(companyUid, name) || !principalUid)
         return null;
     const filePath = path.join(CACHE_DIR, companyUid, name);
     let raw;
@@ -159,6 +182,8 @@ export function readCache(companyUid, name, expectedVersion, maxAgeMs) {
         catch { /* ok */ }
         return null;
     }
+    if (!header.principalDigest?.equals(principalDigest(principalUid)))
+        return null;
     const iv = raw.subarray(header.ivStart, header.authTagStart);
     const authTag = raw.subarray(header.authTagStart, header.ciphertextStart);
     const ciphertext = raw.subarray(header.ciphertextStart);
@@ -171,7 +196,7 @@ export function readCache(companyUid, name, expectedVersion, maxAgeMs) {
     }
     try {
         const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
-        decipher.setAAD(cacheAad(raw.subarray(0, header.ivStart), companyUid, name));
+        decipher.setAAD(cacheAad(raw.subarray(0, header.ivStart), companyUid, name, principalUid));
         decipher.setAuthTag(authTag);
         const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
         return decrypted.toString("utf8");
@@ -189,8 +214,8 @@ export function readCache(companyUid, name, expectedVersion, maxAgeMs) {
  * Callers use this only to decide whether to reauthorize a possible cache hit;
  * they must complete that authorization before calling {@link readCache}.
  */
-export function hasCacheEntry(companyUid, name) {
-    if (!validateInputs(companyUid, name))
+export function hasCacheEntry(companyUid, name, principalUid) {
+    if (!validateInputs(companyUid, name) || !principalUid)
         return false;
     const filePath = path.join(CACHE_DIR, companyUid, name);
     let raw;
@@ -203,18 +228,21 @@ export function hasCacheEntry(companyUid, name) {
     const header = parseCacheHeader(raw);
     if (!header)
         return false;
-    if (!header.identityAuthenticated || isExpired(header)) {
+    if (!header.identityAuthenticated ||
+        isExpired(header)) {
         try {
             fs.unlinkSync(filePath);
         }
         catch { /* ok */ }
         return false;
     }
+    if (!header.principalDigest?.equals(principalDigest(principalUid)))
+        return false;
     return true;
 }
-export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACHE_TTL_MS, version) {
+export function writeCache(companyUid, name, principalUid, value, ttlMs = DEFAULT_SECRETS_CACHE_TTL_MS, version) {
     try {
-        if (!validateInputs(companyUid, name))
+        if (!validateInputs(companyUid, name) || !principalUid)
             return;
         if (ttlMs <= 0)
             return;
@@ -233,9 +261,10 @@ export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACH
             ttl,
             CACHE_VERSION_MARKER,
             versionBuffer,
+            principalDigest(principalUid),
         ]);
         const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
-        cipher.setAAD(cacheAad(header, companyUid, name));
+        cipher.setAAD(cacheAad(header, companyUid, name, principalUid));
         const encrypted = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
         const authTag = cipher.getAuthTag();
         const out = Buffer.concat([
@@ -254,6 +283,125 @@ export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACH
         // Cache write failure is non-fatal
     }
 }
+function scopeCachePath(scopeKey) {
+    const name = crypto.createHash("sha256").update(scopeKey, "utf8").digest("hex");
+    return path.join(CACHE_DIR, SCOPE_KEY_DIR, name);
+}
+function scopeCacheAad(header, scopeKey, principalUid) {
+    const key = Buffer.from(scopeKey, "utf8");
+    const keyLength = Buffer.alloc(4);
+    keyLength.writeUInt32BE(key.length);
+    return Buffer.concat([
+        Buffer.from("HQSC-SCOPE-AAD-V1\0"),
+        header,
+        keyLength,
+        key,
+        principalDigest(principalUid),
+    ]);
+}
+function logScopeCacheFailure(operation, err) {
+    const code = err && typeof err === "object" && "code" in err &&
+        typeof err.code === "string" &&
+        /^[A-Z0-9_]+$/.test(err.code)
+        ? err.code
+        : undefined;
+    console.warn(`Unable to ${operation} cached HQ scope UID`, code ? { code } : {});
+}
+function removeScopeCacheFile(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch (err) {
+        if (!(err &&
+            typeof err === "object" &&
+            "code" in err &&
+            err.code === "ENOENT")) {
+            logScopeCacheFailure("remove", err);
+        }
+    }
+}
+/** Persist the last successfully resolved scope for a principal, encrypted and authenticated. */
+export function writeCachedScopeUid(scopeKey, principalUid, scopeUid) {
+    try {
+        if (!scopeKey || !principalUid || !/^(?:cmp|prs)_[A-Za-z0-9_-]+$/.test(scopeUid))
+            return;
+        fs.mkdirSync(path.join(CACHE_DIR, SCOPE_KEY_DIR), { recursive: true, mode: 0o700 });
+        const key = getOrCreateKey();
+        const timestamp = Buffer.alloc(8);
+        timestamp.writeBigInt64BE(BigInt(Date.now()));
+        const ttl = Buffer.alloc(8);
+        ttl.writeBigInt64BE(BigInt(DEFAULT_SECRETS_CACHE_TTL_MS));
+        const header = Buffer.concat([SCOPE_CACHE_MAGIC, timestamp, ttl, principalDigest(principalUid)]);
+        const iv = crypto.randomBytes(IV_BYTES);
+        const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+        cipher.setAAD(scopeCacheAad(header, scopeKey, principalUid));
+        const encrypted = Buffer.concat([cipher.update(scopeUid, "utf8"), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        const output = Buffer.concat([header, iv, authTag, encrypted]);
+        const filePath = scopeCachePath(scopeKey);
+        const tmpPath = `${filePath}.tmp.${process.pid}`;
+        fs.writeFileSync(tmpPath, output, { mode: 0o600 });
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        // A scope-cache write failure must not change a successful online lookup.
+        logScopeCacheFailure("write", err);
+    }
+}
+/** Return a still-valid scope UID only for the principal that wrote it. */
+export function readCachedScopeUid(scopeKey, principalUid) {
+    if (!scopeKey || !principalUid)
+        return null;
+    const headerBytes = SCOPE_CACHE_MAGIC.length + TIMESTAMP_BYTES + TTL_BYTES + PRINCIPAL_DIGEST_BYTES;
+    const filePath = scopeCachePath(scopeKey);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath);
+    }
+    catch (err) {
+        if (err &&
+            typeof err === "object" &&
+            "code" in err &&
+            err.code === "ENOENT") {
+            return null;
+        }
+        logScopeCacheFailure("read", err);
+        return null;
+    }
+    if (raw.length < headerBytes + IV_BYTES + AUTH_TAG_BYTES || !raw.subarray(0, SCOPE_CACHE_MAGIC.length).equals(SCOPE_CACHE_MAGIC)) {
+        console.warn("Ignoring malformed cached HQ scope UID entry");
+        removeScopeCacheFile(filePath);
+        return null;
+    }
+    const encodedPrincipal = raw.subarray(SCOPE_CACHE_MAGIC.length + TIMESTAMP_BYTES + TTL_BYTES, headerBytes);
+    const timestampMs = Number(raw.readBigInt64BE(SCOPE_CACHE_MAGIC.length));
+    const ttlMs = Number(raw.readBigInt64BE(SCOPE_CACHE_MAGIC.length + TIMESTAMP_BYTES));
+    const ageMs = Date.now() - timestampMs;
+    if (!encodedPrincipal.equals(principalDigest(principalUid)))
+        return null;
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0 || ageMs < 0 || ageMs > ttlMs) {
+        removeScopeCacheFile(filePath);
+        return null;
+    }
+    const ivStart = headerBytes;
+    const authTagStart = ivStart + IV_BYTES;
+    const ciphertextStart = authTagStart + AUTH_TAG_BYTES;
+    try {
+        const decipher = crypto.createDecipheriv(ALGORITHM, getOrCreateKey(), raw.subarray(ivStart, authTagStart));
+        decipher.setAAD(scopeCacheAad(raw.subarray(0, headerBytes), scopeKey, principalUid));
+        decipher.setAuthTag(raw.subarray(authTagStart, ciphertextStart));
+        const scopeUid = Buffer.concat([
+            decipher.update(raw.subarray(ciphertextStart)),
+            decipher.final(),
+        ]).toString("utf8");
+        return /^(?:cmp|prs)_[A-Za-z0-9_-]+$/.test(scopeUid) ? scopeUid : null;
+    }
+    catch (err) {
+        logScopeCacheFailure("decrypt", err);
+        removeScopeCacheFile(filePath);
+        return null;
+    }
+}
 /**
  * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
  * secrets-cache directory on disk. Install-time MCP registration may use an

package/dist/utils/vault-api.d.ts

@@ -67,10 +67,14 @@ export declare function getCompanyUid(token: string, companySlug: string | undef
  * pass it when the caller is bound to another API (an enrolled agent's
  * `apiBaseUrl`) so its token never goes to the default host.
  */
-baseUrl?: string): Promise<string>;
+baseUrl?: string, options?: {
+    allowOfflineScopeFallback?: boolean;
+}): Promise<string>;
 export declare function resolveCallerPersonUid(token: string, baseUrl?: string): Promise<string>;
 export declare function getEntityUid(token: string, opts: {
     personal?: boolean;
     companySlug?: string;
+}, options?: {
+    allowOfflineScopeFallback?: boolean;
 }): Promise<string>;
 //# sourceMappingURL=vault-api.d.ts.map

package/dist/utils/vault-api.js

@@ -1,4 +1,4 @@
-import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
+import { DEFAULT_VAULT_API_URL, cognitoCachePrincipalUid } from './cognito-session.js';
 import { CLI_VERSION } from '../cli-version.js';
 import { Sentry } from '../sentry.js';
 import { AuthError } from './auth-error.js';
@@ -8,6 +8,8 @@ import { networkTransportErrorCode } from './network-transport-error.js';
 import { planGateErrorFromResponse } from './plan-gate-error.js';
 import { markExpectedUserError } from './expected-cli-error.js';
 import { redactErrorText } from './redact-error-text.js';
+import { isSecretLoadUnavailable, isUnavailableSecretLoadHttpStatus, SecretLoadUnavailableError } from './secret-load-availability.js';
+import { readCachedScopeUid, writeCachedScopeUid } from './secrets-cache.js';
 /**
  * Identity / company resolution lookups must never hang forever. These small
  * GETs run BEFORE a command does its real work (e.g. `hq secrets env` resolves
@@ -47,8 +49,9 @@ function identityLookupTimeoutMs() {
  * call .json()/.text()/.arrayBuffer(). Non-JSON and non-ok responses are
  * returned untouched (streamed binary downloads must never be buffered).
  *
- * Never throws. On any error: return the original response if its body has
- * not been consumed, otherwise the re-wrapped one.
+ * On inspection errors, return the original response by default to preserve
+ * existing behavior. Secret-load callers opt into rethrowing body read errors
+ * so the load path can classify a broken stream for offline-cache fallback.
  *
  * Why not response.clone()? Cloning tees the undici body stream; when a
  * caller never consumes the original Response body (many commands only check
@@ -56,7 +59,7 @@ function identityLookupTimeoutMs() {
  * referenced and the process (or vitest worker / spawned CLI child) never
  * exits on Linux CI. Reading once + re-wrapping fully drains the stream.
  */
-async function peekPlanLimitStatus(response) {
+async function peekPlanLimitStatus(response, options = {}) {
     try {
         if (!response.ok)
             return response;
@@ -64,14 +67,7 @@ async function peekPlanLimitStatus(response) {
         if (!ct.includes('application/json') && !ct.includes('+json')) {
             return response;
         }
-        let buf;
-        try {
-            buf = await response.arrayBuffer();
-        }
-        catch {
-            // Body may be locked/errored; original is the only thing we can return.
-            return response;
-        }
+        const buf = await response.arrayBuffer();
         try {
             const text = new TextDecoder().decode(buf);
             try {
@@ -92,9 +88,11 @@ async function peekPlanLimitStatus(response) {
             headers: response.headers,
         });
     }
-    catch {
-        // Outer safety net: never throw from the peek path. If we never consumed
-        // the body, the original is still usable.
+    catch (err) {
+        // Only secret-load callers need the body-read error for offline fallback.
+        // Other endpoints retain the pre-existing best-effort peek behavior.
+        if (options.throwOnBodyReadError)
+            throw err;
         return response;
     }
 }
@@ -238,7 +236,21 @@ export async function vaultApiFetch(opts) {
             throw planGate.error;
         return planGate.response;
     }
-    return peekPlanLimitStatus(response);
+    const isSecretLoad = method === "POST" && /^\/secrets\/[^/]+\/load$/.test(path);
+    try {
+        return await peekPlanLimitStatus(response, {
+            throwOnBodyReadError: isSecretLoad,
+        });
+    }
+    catch (err) {
+        // A successful /load response whose JSON stream breaks is a transient
+        // transport failure for offline-cache purposes, even when undici has
+        // already reduced its cause to a generic body-reader TypeError.
+        if (isSecretLoad) {
+            throw new SecretLoadUnavailableError("Failed to read the secret load response body", { cause: err });
+        }
+        throw err;
+    }
 }
 /**
  * Public (NONE-auth) GET against the vault API — no bearer token. The
@@ -324,6 +336,9 @@ async function resolveCompanyByUid(token, uid, baseUrl) {
     if (!res.ok) {
         raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
+        if (isUnavailableSecretLoadHttpStatus(res.status)) {
+            throw new SecretLoadUnavailableError(`Failed to resolve company '${uid}': ${formatSlugLookupReason(res, body)}`);
+        }
         throw new Error(`Failed to resolve company '${uid}': ${formatSlugLookupReason(res, body)}`);
     }
     const data = (await res.json());
@@ -492,6 +507,9 @@ async function resolveCompanyUid(token, ref, baseUrl) {
             ? " This is a temporary lookup failure, not a missing company. Retry the command."
             : "";
         const error = new Error(redactedSlugLookupMessage(`Failed to resolve company slug '${ref}': ${reason}.${hint}`));
+        if (retryable && (mine.kind === "transient" || isUnavailableSecretLoadHttpStatus(res.status))) {
+            throw new SecretLoadUnavailableError(error.message);
+        }
         throw retryable ? error : markExpectedUserError(error);
     }
     const data = (await res.json());
@@ -506,6 +524,9 @@ async function resolveCompanyFromMemberships(token, baseUrl) {
     });
     if (!res.ok) {
         const error = new Error("Failed to fetch memberships — run `hq login` and try again");
+        if (isUnavailableSecretLoadHttpStatus(res.status)) {
+            throw new SecretLoadUnavailableError(error.message);
+        }
         throw res.status === 401 ? markExpectedUserError(error) : error;
     }
     const data = (await res.json());
@@ -529,7 +550,7 @@ export async function getCompanyUid(token, companySlug,
  * pass it when the caller is bound to another API (an enrolled agent's
  * `apiBaseUrl`) so its token never goes to the default host.
  */
-baseUrl) {
+baseUrl, options = {}) {
     // Vault API keys are company-bound. Entity slug resolution has no keyed
     // route, so under hqk_ we accept an explicit cmp_ uid (or HQ_COMPANY_UID)
     // and otherwise fall through to keyed GET /v1/keys/membership/me.
@@ -544,10 +565,29 @@ baseUrl) {
         }
         return resolveCompanyFromMemberships(token, baseUrl);
     }
-    if (companySlug) {
-        return resolveCompanyUid(token, companySlug, baseUrl);
+    if (!options.allowOfflineScopeFallback) {
+        return companySlug
+            ? resolveCompanyUid(token, companySlug, baseUrl)
+            : resolveCompanyFromMemberships(token, baseUrl);
+    }
+    const scopeKey = `company:${companySlug ?? "<active-membership>"}`;
+    const principalUid = cognitoCachePrincipalUid(token);
+    try {
+        const uid = companySlug
+            ? await resolveCompanyUid(token, companySlug, baseUrl)
+            : await resolveCompanyFromMemberships(token, baseUrl);
+        if (principalUid)
+            writeCachedScopeUid(scopeKey, principalUid, uid);
+        return uid;
+    }
+    catch (err) {
+        if (!principalUid || !isSecretLoadUnavailable(err))
+            throw err;
+        const cachedUid = readCachedScopeUid(scopeKey, principalUid);
+        if (!cachedUid)
+            throw err;
+        return cachedUid;
     }
-    return resolveCompanyFromMemberships(token, baseUrl);
 }
 // Same selection rule as the backend's `resolveCallerPersonUid`: ascending by
 // createdAt, tie-break by uid ascending. Returns the `prs_*` UID.
@@ -559,6 +599,9 @@ export async function resolveCallerPersonUid(token, baseUrl) {
         signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
+        if (isUnavailableSecretLoadHttpStatus(res.status)) {
+            throw new SecretLoadUnavailableError("Failed to fetch person entity — run `hq login` and try again");
+        }
         throw new Error("Failed to fetch person entity — run `hq login` and try again");
     }
     const data = (await res.json());
@@ -578,10 +621,26 @@ export async function resolveCallerPersonUid(token, baseUrl) {
 // Resolves the scope UID (cmp_* or prs_*) for a secrets command. Precedence:
 // `--personal` → caller's canonical person entity; else `--company <slug>` →
 // resolved company UID; else fallback to single active company membership.
-export async function getEntityUid(token, opts) {
+export async function getEntityUid(token, opts, options = {}) {
     if (opts.personal) {
-        return resolveCallerPersonUid(token);
+        if (!options.allowOfflineScopeFallback)
+            return resolveCallerPersonUid(token);
+        const principalUid = cognitoCachePrincipalUid(token);
+        try {
+            const uid = await resolveCallerPersonUid(token);
+            if (principalUid)
+                writeCachedScopeUid("personal", principalUid, uid);
+            return uid;
+        }
+        catch (err) {
+            if (!principalUid || !isSecretLoadUnavailable(err))
+                throw err;
+            const cachedUid = readCachedScopeUid("personal", principalUid);
+            if (!cachedUid)
+                throw err;
+            return cachedUid;
+        }
     }
-    return getCompanyUid(token, opts.companySlug);
+    return getCompanyUid(token, opts.companySlug, undefined, options);
 }
 //# sourceMappingURL=vault-api.js.map

package/package.json

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