@indigoai-us/hq-cli 5.314.0 → 5.316.0

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';
@@ -6,6 +6,10 @@ import { CompanySelectionError } from './company-selection-error.js';
 import { recordPlanLimitStatus } from '../lib/plan-limit-nag.js';
 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
@@ -45,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
@@ -54,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;
@@ -62,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 {
@@ -90,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;
     }
 }
@@ -155,7 +155,7 @@ export function rewritePathForApiKey(path) {
  * authorization or request signing depends on it.
  */
 export const HQ_CLIENT_NAME = "@indigoai-us/hq-cli";
-export async function vaultApiFetch(opts) {
+function resolveVaultApiRequestTarget(opts) {
     let path = opts.path;
     if (opts.token.startsWith("hqk_")) {
         const rewritten = rewritePathForApiKey(path);
@@ -172,6 +172,18 @@ export async function vaultApiFetch(opts) {
             url.searchParams.set(k, v);
         }
     }
+    return { path, url };
+}
+/**
+ * Run vaultApiFetch's synchronous, client-side request checks without sending
+ * the request. Commands with prior uploads use this to fail before creating
+ * objects that a later local refusal would leave orphaned.
+ */
+export function assertVaultApiRequestSupported(opts) {
+    resolveVaultApiRequestTarget(opts);
+}
+export async function vaultApiFetch(opts) {
+    const { path, url } = resolveVaultApiRequestTarget(opts);
     const method = opts.method ?? 'GET';
     const safeUrl = url.search ? `${url.origin}${url.pathname}?<redacted>` : `${url.origin}${url.pathname}`;
     Sentry.addBreadcrumb({
@@ -193,6 +205,7 @@ export async function vaultApiFetch(opts) {
                 // skew on EVERY authenticated request, not only health heartbeats.
                 // Fixed build constant, never caller-supplied; attribution only.
                 'x-hq-client-version': CLI_VERSION,
+                ...opts.headers,
             },
             body: opts.body ? JSON.stringify(opts.body) : undefined,
             signal: opts.signal,
@@ -235,7 +248,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
@@ -285,6 +312,24 @@ const COMPANY_UID_PREFIX = 'cmp_';
 export function looksLikeCompanyUid(ref) {
     return ref.startsWith(COMPANY_UID_PREFIX);
 }
+/**
+ * A `--company` value beginning with `prs_` names a PERSON'S vault, not a
+ * company. It is the only way to reach a DM attachment: the file lives in the
+ * SENDER's personal vault under
+ * `chat/attachments/dm/<uidA>--<uidB>/…`, and the vault API authorizes either
+ * member of that pair to `get` it (hq-pro #3571). The recipient has no
+ * personal vault of their own (so `--personal` cannot work) and the key is not
+ * in any company bucket (so a slug 404s on the object), which left the read
+ * with no expressible scope at all.
+ *
+ * Routed straight through as the scope uid: person entities have no slug
+ * namespace, so there is nothing to resolve, and the server's own per-key gate
+ * — not the CLI — decides whether the caller may read it.
+ */
+const PERSON_VAULT_UID_PREFIX = 'prs_';
+export function looksLikePersonVaultUid(ref) {
+    return ref.startsWith(PERSON_VAULT_UID_PREFIX);
+}
 // A 401 from ANY vault resolution call means the caller's HQ session is
 // expired or missing — an expected auth state fixed by `hq login`, not a
 // code defect. Raise a typed AuthError so the top-level handler prints an
@@ -293,25 +338,53 @@ function raiseIfUnauthorized(res) {
     if (res.status === 401)
         throw new AuthError();
 }
-async function resolveCompanyByUid(token, uid) {
+async function resolveCompanyByUid(token, uid, baseUrl) {
     const res = await vaultApiFetch({
         token,
         path: `/entity/${encodeURIComponent(uid)}`,
+        baseUrl,
         signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
         raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
-        throw new Error(`Failed to resolve company '${uid}': ${body.error ?? res.statusText}`);
+        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());
     return data.entity.uid;
 }
+/**
+ * Node's fetch (undici) often leaves `statusText` empty, and some vault
+ * error bodies send `error: ""` or omit it. `??` does not treat "" as missing,
+ * so `body.error ?? res.statusText` produced
+ * `Failed to resolve company slug '…':` with nothing after the colon
+ * (Shepherd #2306). Never return an empty reason: prefer a non-blank body
+ * error, then statusText, then `HTTP <status>`.
+ */
+function formatSlugLookupReason(res, body) {
+    const fromBody = typeof body.error === "string" ? body.error.trim() : "";
+    if (fromBody)
+        return fromBody;
+    const fromStatus = (res.statusText ?? "").trim();
+    if (fromStatus)
+        return fromStatus;
+    return `HTTP ${res.status}`;
+}
+function redactedSlugLookupMessage(message) {
+    return redactErrorText(message) || 'Company lookup failed.';
+}
+function isTransientSlugLookupStatus(status) {
+    return status === 408 || status === 425 || status === 429 || status >= 500;
+}
 /**
  * Resolve a company slug WITHIN THE CALLER'S NAMESPACE via the server's
  * caller-scoped `/entity/check-slug/me` endpoint. Returns the caller's own
- * company uid for that slug, or `null` when the caller owns / actively belongs
- * to no company with that slug.
+ * company uid for that slug, `miss` when the caller owns / actively belongs
+ * to no company with that slug, or `transient` when the lookup itself failed
+ * (timeout, 429, 5xx) after one retry.
  *
  * This is the load-bearing fix for DEV-1742. Under hq-pro's per-user-namespace
  * model two unrelated tenants may each hold "acme", so the legacy GLOBAL
@@ -325,69 +398,101 @@ async function resolveCompanyByUid(token, uid) {
  * stranger's same-slug company is correctly invisible to resolution. This is
  * the same primitive hq-cloud's `context.ts` already resolves slugs through.
  */
-async function resolveSlugInCallerNamespace(token, slug) {
-    const res = await vaultApiFetch({
+async function resolveSlugInCallerNamespace(token, slug, baseUrl) {
+    const attempt = async () => {
+        const res = await vaultApiFetch({
+            token,
+            path: "/entity/check-slug/me",
+            baseUrl,
+            query: { type: "company", slug },
+            signal: AbortSignal.timeout(identityLookupTimeoutMs()),
+        });
+        if (!res.ok) {
+            raiseIfUnauthorized(res);
+            // Namespace lookup unavailable (e.g. membership table not configured →
+            // 503, or the caller has no person entity). A 401 short-circuits above
+            // because the token is bad and the global fallback would only 401 again.
+            // Transient statuses are retried once below; other non-2xx still mean
+            // "couldn't resolve here" and fall back to the global lookup.
+            // vaultApiFetch already recorded the non-2xx as a Sentry breadcrumb.
+            if (isTransientSlugLookupStatus(res.status)) {
+                return { kind: "transient" };
+            }
+            return { kind: "miss" };
+        }
+        const data = (await res.json());
+        // `available: false` carries the caller's own company holding the slug.
+        const uid = data.conflictingCompanyUid;
+        return uid ? { kind: "hit", uid } : { kind: "miss" };
+    };
+    const run = async () => {
+        try {
+            return await attempt();
+        }
+        catch (err) {
+            if (networkTransportErrorCode(err) === null)
+                throw err;
+            return { kind: "transient" };
+        }
+    };
+    const first = await run();
+    if (first.kind !== "transient")
+        return first;
+    return run();
+}
+async function fetchGlobalCompanyBySlug(token, ref, baseUrl) {
+    const attempt = () => vaultApiFetch({
         token,
-        path: '/entity/check-slug/me',
-        query: { type: 'company', slug },
+        path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
+        baseUrl,
         signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
-    if (!res.ok) {
-        raiseIfUnauthorized(res);
-        // Namespace lookup unavailable (e.g. membership table not configured →
-        // 503, or the caller has no person entity). A 401 short-circuits above
-        // because the token is bad and the global fallback would only 401 again;
-        // other non-2xx statuses signal "couldn't resolve here" and let the caller
-        // fall back to the global lookup. vaultApiFetch already recorded the
-        // non-2xx as a Sentry breadcrumb, so this is not a silent swallow.
-        return null;
+    try {
+        const res = await attempt();
+        if (res.ok || !isTransientSlugLookupStatus(res.status))
+            return res;
     }
-    const data = (await res.json());
-    // `available: false` carries the caller's own company holding the slug.
-    return data.conflictingCompanyUid ?? null;
+    catch (err) {
+        if (networkTransportErrorCode(err) === null)
+            throw err;
+        return attempt();
+    }
+    return attempt();
 }
-async function resolveCompanyUid(token, ref) {
+async function resolveCompanyUid(token, ref, baseUrl) {
     // Silent escape hatch: a `cmp_` ref is a uid, not a slug — resolve directly.
     if (looksLikeCompanyUid(ref)) {
-        return resolveCompanyByUid(token, ref);
+        return resolveCompanyByUid(token, ref, baseUrl);
+    }
+    // A `prs_` ref names a person's vault (DM attachments). There is no slug to
+    // resolve and no company lookup that could succeed; pass it through as the
+    // scope and let the vault API's per-key authorization answer.
+    if (looksLikePersonVaultUid(ref)) {
+        return ref;
     }
     // PRIMARY PATH — caller-scoped slug resolution. Resolves the slug to the
     // caller's OWN company (unique within their namespace by the invariant
     // above), making a stranger's same-slug company invisible.
     //
-    // A non-2xx already degrades to the global fallback below (via `return null`).
-    // A TRANSPORT failure must degrade the SAME way, not abort the command:
-    // `resolveSlugInCallerNamespace`'s fetch is bounded by AbortSignal.timeout, so
-    // a vault gateway that accepts the connection but never answers rejects with a
-    // DOMException named `TimeoutError`. Before this catch, that rejection threw
-    // straight out of `resolveCompanyUid`, skipped the global by-slug lookup, and
-    // — being unclassified by main.ts — filed a Sentry crash report instead of an
-    // actionable connectivity message (Sentry HQ-CLI-1P / issue 7716090679).
-    // Degrade ONLY on a recognized transport failure; re-throw everything else
-    // unchanged, so a genuine hq-cli defect stays fatal and the 401 AuthError that
-    // `raiseIfUnauthorized` throws still short-circuits before any fallback.
-    let mine;
-    try {
-        mine = await resolveSlugInCallerNamespace(token, ref);
+    // A non-2xx already degrades to the global fallback below (`miss` /
+    // `transient`). A TRANSPORT failure must degrade the SAME way, not abort
+    // the command: `resolveSlugInCallerNamespace`'s fetch is bounded by
+    // AbortSignal.timeout, so a vault gateway that accepts the connection but
+    // never answers rejects with a DOMException named `TimeoutError`. That is
+    // classified as `transient` (and retried once) inside the helper; a genuine
+    // hq-cli defect still throws, and the 401 AuthError that
+    // `raiseIfUnauthorized` throws still short-circuits before any fallback
+    // (Sentry HQ-CLI-1P / issue 7716090679).
+    const mine = await resolveSlugInCallerNamespace(token, ref, baseUrl);
+    if (mine.kind === "hit") {
+        return mine.uid;
     }
-    catch (err) {
-        if (networkTransportErrorCode(err) === null) {
-            throw err;
-        }
-        mine = null;
-    }
-    if (mine) {
-        return mine;
-    }
-    // The caller owns / belongs to no company with this slug. Fall back to the
-    // GLOBAL by-slug lookup for the cross-company / admin resolutions that
-    // intentionally target a company the caller isn't a member of (e.g. a
-    // group-grant target). A single global match resolves cleanly.
-    const res = await vaultApiFetch({
-        token,
-        path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
-        signal: AbortSignal.timeout(identityLookupTimeoutMs()),
-    });
+    // The caller owns / belongs to no company with this slug, or the namespace
+    // lookup itself failed. Fall back to the GLOBAL by-slug lookup for the
+    // cross-company / admin resolutions that intentionally target a company the
+    // caller isn't a member of (e.g. a group-grant target). A single global
+    // match resolves cleanly.
+    const res = await fetchGlobalCompanyBySlug(token, ref, baseUrl);
     if (!res.ok) {
         raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
@@ -401,22 +506,40 @@ async function resolveCompanyUid(token, ref) {
                 `is in your namespace. Re-run with --company <uid> to pick one:\n` +
                 body.uids.map((u) => `  --company ${u}`).join('\n'));
         }
-        if (res.status === 404 && body.error === "Entity not found") {
-            throw Object.assign(new Error(`Company slug '${ref}' was not found. Check the slug or run \`hq companies list\`.`), { expected: true });
+        // Only a clean namespace miss plus a global 404 is "this slug does not
+        // exist". A transient namespace failure followed by 404 is still a lookup
+        // failure — treating it as not-found sent owners to check a slug that
+        // was fine (Shepherd #2306).
+        if (res.status === 404 && mine.kind === "miss") {
+            throw Object.assign(new Error(redactedSlugLookupMessage(`Company slug '${ref}' was not found. Check the slug or run \`hq sources entities\`.`)), { expected: true });
         }
-        throw new Error(`Failed to resolve company slug '${ref}': ${body.error ?? res.statusText}`);
+        const reason = formatSlugLookupReason(res, body);
+        const retryable = mine.kind === "transient" || isTransientSlugLookupStatus(res.status);
+        const hint = retryable
+            ? " 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());
     return data.entity.uid;
 }
-async function resolveCompanyFromMemberships(token) {
+async function resolveCompanyFromMemberships(token, baseUrl) {
     const res = await vaultApiFetch({
         token,
         path: '/membership/me',
+        baseUrl,
         signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
-        throw new Error("Failed to fetch memberships — run `hq login` and try again");
+        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());
     const active = data.memberships.filter((m) => m.status === 'active');
@@ -433,7 +556,13 @@ async function resolveCompanyFromMemberships(token) {
         `pick one:\n` +
         picks.join('\n'));
 }
-export async function getCompanyUid(token, companySlug) {
+export async function getCompanyUid(token, companySlug, 
+/**
+ * Control-plane origin for the lookups. Defaults to DEFAULT_VAULT_API_URL;
+ * 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, 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.
@@ -446,12 +575,31 @@ export async function getCompanyUid(token, companySlug) {
             }
             return ref;
         }
-        return resolveCompanyFromMemberships(token);
+        return resolveCompanyFromMemberships(token, baseUrl);
+    }
+    if (!options.allowOfflineScopeFallback) {
+        return companySlug
+            ? resolveCompanyUid(token, companySlug, baseUrl)
+            : resolveCompanyFromMemberships(token, baseUrl);
     }
-    if (companySlug) {
-        return resolveCompanyUid(token, companySlug);
+    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);
 }
 // Same selection rule as the backend's `resolveCallerPersonUid`: ascending by
 // createdAt, tie-break by uid ascending. Returns the `prs_*` UID.
@@ -463,6 +611,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());
@@ -482,10 +633,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/dist/utils/version-check.d.ts

@@ -1,3 +1,4 @@
+export declare const CLI_VERSION_NUDGE_FLAG = "cli.version-update-nudge";
 declare function isKnownNoninteractiveStatusProbe(argv?: readonly string[]): boolean;
 /**
  * The cached npm `latest` when it is newer than the running version, else null.
@@ -17,7 +18,16 @@ export declare function staleAgainstCachedLatest(now?: number): string | null;
  * means the loop guard is skipped this once, never a broken CLI.
  */
 export declare function markLatestIneffective(version: string, now?: number): void;
-export declare function refreshVersionCache(): Promise<void>;
+export interface RefreshVersionCacheOptions {
+    timeoutMs?: number;
+}
+export declare function refreshVersionCache(options?: RefreshVersionCacheOptions): Promise<void>;
+/** Write the optional update guidance from the existing npm version cache.
+ * This helper never performs a network request; a missing or stale cache means
+ * there is no nudge to show.
+ */
+export declare function printCachedVersionNudge(stderr?: Pick<NodeJS.WriteStream, "write">): Promise<void>;
+export declare function printVersionAndNudge(stdout?: Pick<NodeJS.WriteStream, "write">, stderr?: Pick<NodeJS.WriteStream, "write">): Promise<void>;
 export declare const __test__: {
     CACHE_TTL_MS: number;
     isKnownNoninteractiveStatusProbe: typeof isKnownNoninteractiveStatusProbe;

package/dist/utils/version-check.js

@@ -9,6 +9,7 @@ const CACHE_TTL_MS = 60 * 60 * 1000; // 1h — catch fresh releases within the h
 const CACHE_TTL_JITTER_MS = 5 * 60 * 1000; // up to 5m early, to spread a fleet's refreshes off a single instant
 const FETCH_TIMEOUT_MS = 3_000;
 const REFRESH_LOCK_STALE_MS = 10 * 60 * 1000;
+export const CLI_VERSION_NUDGE_FLAG = "cli.version-update-nudge";
 /**
  * How long to stop auto-retrying an `ineffectiveLatest` target. Long enough to
  * break the per-invocation loop on a busy agent box, short enough that a box
@@ -67,7 +68,7 @@ function isKnownNoninteractiveStatusProbe(argv = process.argv) {
     const json = args.includes("--json") || !process.stdout.isTTY;
     if (!json)
         return false;
-    if (positional[0] === "mcp" && positional[1] === "status")
+    if (positional[0] === "mcp" && (positional[1] === "status" || positional[1] === "list"))
         return true;
     if (positional[0] === "packs" && (positional[1] === "list" || positional[1] === "ls"))
         return true;
@@ -166,7 +167,7 @@ export function markLatestIneffective(version, now = Date.now()) {
         ineffectiveAt: now,
     });
 }
-export async function refreshVersionCache() {
+export async function refreshVersionCache(options = {}) {
     if (isOptedOut())
         return;
     if (isKnownNoninteractiveStatusProbe())
@@ -183,7 +184,7 @@ export async function refreshVersionCache() {
             return;
         const res = await fetch(REGISTRY_URL, {
             headers: { Accept: "application/json" },
-            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            signal: AbortSignal.timeout(options.timeoutMs ?? FETCH_TIMEOUT_MS),
         });
         if (!res.ok)
             return;
@@ -199,6 +200,34 @@ export async function refreshVersionCache() {
         releaseLock();
     }
 }
+/** Write the optional update guidance from the existing npm version cache.
+ * This helper never performs a network request; a missing or stale cache means
+ * there is no nudge to show.
+ */
+export async function printCachedVersionNudge(stderr = process.stderr) {
+    if (isOptedOut())
+        return;
+    let resolveProcessFlagGate;
+    try {
+        ({ resolveProcessFlagGate } = await import("../lib/flag-registry.js"));
+    }
+    catch (error) {
+        const errorClass = error instanceof Error ? error.name : "unknown";
+        stderr.write(`hq: Update nudge unavailable (${errorClass}).\n`);
+        return;
+    }
+    const enabled = resolveProcessFlagGate(CLI_VERSION_NUDGE_FLAG, { fallback: false }, () => false);
+    if (!enabled)
+        return;
+    const latest = staleAgainstCachedLatest();
+    if (latest) {
+        stderr.write(`Update available: ${latest}. Update with npm install -g @indigoai-us/hq-cli@latest, pnpm add -g @indigoai-us/hq-cli@latest, or bun add -g @indigoai-us/hq-cli@latest.\n`);
+    }
+}
+export async function printVersionAndNudge(stdout = process.stdout, stderr = process.stderr) {
+    stdout.write(`${CLI_VERSION}\n`);
+    await printCachedVersionNudge(stderr);
+}
 export const __test__ = {
     CACHE_TTL_MS,
     isKnownNoninteractiveStatusProbe,