@indigoai-us/hq-cli 5.60.0 → 5.61.0

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

@@ -1,6 +1,13 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3cbec729-3b2b-5d53-9e90-5680dd725b7d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e77a0f25-ac1a-574f-a1e4-985c6b3306d7")}catch(e){}}();
 const DEFAULT_SANDBOX_RUNNER_URL = "https://hqapi.getindigo.ai/sandbox";
+const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
+const DEFAULT_RETRY_OPTIONS = {
+    maxAttempts: 8,
+    maxElapsedMs: 90_000,
+    baseDelayMs: 500,
+    maxDelayMs: 5_000,
+};
 function normalizeBaseUrl(baseUrl) {
     return baseUrl.replace(/\/+$/, "");
 }
@@ -40,15 +47,85 @@ function delay(ms) {
         return Promise.resolve();
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    return String(error);
+}
+function parseRetryAfterMs(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1000;
+    }
+    const dateMs = Date.parse(value);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - Date.now());
+    }
+    return undefined;
+}
 export class SandboxRunnerClient {
     baseUrl;
     fetchImpl;
+    retry;
+    sleep;
     constructor(options = {}) {
         this.baseUrl = normalizeBaseUrl(options.baseUrl ?? getSandboxRunnerBaseUrl());
         this.fetchImpl = options.fetchImpl ?? fetch;
+        this.retry = { ...DEFAULT_RETRY_OPTIONS, ...options.retry };
+        this.sleep = options.sleep ?? delay;
+    }
+    async fetchWithRetry(url, init) {
+        const startedAt = Date.now();
+        let lastError = "unknown error";
+        let attempts = 0;
+        for (let attempt = 1; attempt <= this.retry.maxAttempts; attempt += 1) {
+            attempts = attempt;
+            try {
+                const res = await this.fetchImpl(url, init);
+                if (!RETRYABLE_STATUS_CODES.has(res.status)) {
+                    return res;
+                }
+                lastError = `HTTP ${res.status} ${res.statusText}`.trim();
+                if (!this.shouldRetry(attempt, startedAt)) {
+                    break;
+                }
+                await this.sleep(this.nextDelayMs(attempt, res));
+            }
+            catch (error) {
+                lastError = getErrorMessage(error);
+                if (!this.shouldRetry(attempt, startedAt)) {
+                    break;
+                }
+                await this.sleep(this.nextDelayMs(attempt));
+            }
+        }
+        throw new Error(`Sandbox Runner did not respond after ${attempts} attempts ` +
+            `(cold start or transient network); last error: ${lastError}`);
+    }
+    shouldRetry(attempt, startedAt) {
+        if (attempt >= this.retry.maxAttempts) {
+            return false;
+        }
+        return Date.now() - startedAt < this.retry.maxElapsedMs;
+    }
+    nextDelayMs(attempt, res) {
+        const retryAfterMs = parseRetryAfterMs(res?.headers.get("Retry-After") ?? null);
+        if (retryAfterMs !== undefined) {
+            return Math.min(retryAfterMs, this.retry.maxDelayMs);
+        }
+        const exponential = this.retry.baseDelayMs * 2 ** (attempt - 1);
+        const capped = Math.min(exponential, this.retry.maxDelayMs);
+        const jitter = Math.floor(Math.random() * Math.max(1, capped * 0.25));
+        return Math.min(capped + jitter, this.retry.maxDelayMs);
     }
     async startJob(token, request) {
-        const res = await this.fetchImpl(`${this.baseUrl}/jobs`, {
+        const res = await this.fetchWithRetry(`${this.baseUrl}/jobs`, {
             method: "POST",
             headers: {
                 Authorization: `Bearer ${token}`,
@@ -75,7 +152,7 @@ export class SandboxRunnerClient {
         };
     }
     async getJob(token, jobId) {
-        const res = await this.fetchImpl(`${this.baseUrl}/jobs/${encodeURIComponent(jobId)}`, {
+        const res = await this.fetchWithRetry(`${this.baseUrl}/jobs/${encodeURIComponent(jobId)}`, {
             headers: { Authorization: `Bearer ${token}` },
         });
         const body = await parseJsonResponse(res);
@@ -97,10 +174,10 @@ export class SandboxRunnerClient {
             if (job.status === "succeeded" || job.status === "failed") {
                 return job;
             }
-            await delay(intervalMs);
+            await this.sleep(intervalMs);
         }
         throw new Error(`Sandbox Runner job '${jobId}' did not finish before the poll limit.`);
     }
 }
 //# sourceMappingURL=sandbox-runner-client.js.map
-//# debugId=3cbec729-3b2b-5d53-9e90-5680dd725b7d
+//# debugId=e77a0f25-ac1a-574f-a1e4-985c6b3306d7

package/dist/utils/version-check.d.ts

@@ -1,3 +1,9 @@
+declare function isKnownNoninteractiveStatusProbe(argv?: readonly string[]): boolean;
 export declare function maybeWarnNewVersion(): void;
 export declare function refreshVersionCache(): Promise<void>;
+export declare const __test__: {
+    CACHE_TTL_MS: number;
+    isKnownNoninteractiveStatusProbe: typeof isKnownNoninteractiveStatusProbe;
+};
+export {};
 //# sourceMappingURL=version-check.d.ts.map

package/dist/utils/version-check.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="99545a82-414c-5fed-a478-ea8e63009643")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f7058fc6-251e-5e11-af6c-de15f6e256f3")}catch(e){}}();
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -9,10 +9,15 @@ import { CLI_VERSION } from "../cli-version.js";
 const PACKAGE_NAME = "@indigoai-us/hq-cli";
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const CACHE_TTL_JITTER_MS = 60 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 3_000;
+const REFRESH_LOCK_STALE_MS = 10 * 60 * 1000;
 function cachePath() {
     return path.join(os.homedir(), ".hq", "version-check.json");
 }
+function lockPath() {
+    return path.join(os.homedir(), ".hq", "version-check.lock");
+}
 function isOptedOut() {
     return process.env.HQ_NO_UPDATE_CHECK === "1";
 }
@@ -40,6 +45,59 @@ function writeCache(entry) {
         // best-effort; never break the CLI on cache write failure
     }
 }
+function freshEnough(entry, now = Date.now()) {
+    const jitter = Math.floor(Math.random() * CACHE_TTL_JITTER_MS);
+    return now - entry.fetchedAt <= CACHE_TTL_MS - jitter;
+}
+function isKnownNoninteractiveStatusProbe(argv = process.argv) {
+    const args = argv.slice(2);
+    const positional = args.filter((arg) => !arg.startsWith("-"));
+    const json = args.includes("--json") || !process.stdout.isTTY;
+    if (!json)
+        return false;
+    if (positional[0] === "mcp" && positional[1] === "status")
+        return true;
+    if (positional[0] === "packs" && (positional[1] === "list" || positional[1] === "ls"))
+        return true;
+    if (positional[0] === "packages" &&
+        positional[1] === "packs" &&
+        (positional[2] === "list" || positional[2] === "ls")) {
+        return true;
+    }
+    if ((positional[0] === "sources" || positional[0] === "signals") && positional[1] === "list") {
+        return true;
+    }
+    return false;
+}
+function acquireRefreshLock(now = Date.now()) {
+    const dir = lockPath();
+    try {
+        fs.mkdirSync(path.dirname(dir), { recursive: true });
+        fs.mkdirSync(dir);
+        fs.writeFileSync(path.join(dir, "owner"), `${process.pid}\n${now}\n`);
+        return () => {
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // best-effort lock cleanup
+            }
+        };
+    }
+    catch {
+        try {
+            const stat = fs.statSync(dir);
+            if (now - stat.mtimeMs > REFRESH_LOCK_STALE_MS) {
+                fs.rmSync(dir, { recursive: true, force: true });
+                return acquireRefreshLock(now);
+            }
+        }
+        catch {
+            // ignore lock inspection failures
+        }
+        return null;
+    }
+}
 export function maybeWarnNewVersion() {
     if (isOptedOut())
         return;
@@ -60,7 +118,18 @@ export function maybeWarnNewVersion() {
 export async function refreshVersionCache() {
     if (isOptedOut())
         return;
+    if (isKnownNoninteractiveStatusProbe())
+        return;
+    const existing = readCache();
+    if (existing && freshEnough(existing))
+        return;
+    const releaseLock = acquireRefreshLock();
+    if (!releaseLock)
+        return;
     try {
+        const lockedExisting = readCache();
+        if (lockedExisting && freshEnough(lockedExisting))
+            return;
         const res = await fetch(REGISTRY_URL, {
             headers: { Accept: "application/json" },
             signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
@@ -75,6 +144,13 @@ export async function refreshVersionCache() {
     catch {
         // best-effort; offline / registry down / timeout — silent
     }
+    finally {
+        releaseLock();
+    }
 }
+export const __test__ = {
+    CACHE_TTL_MS,
+    isKnownNoninteractiveStatusProbe,
+};
 //# sourceMappingURL=version-check.js.map
-//# debugId=99545a82-414c-5fed-a478-ea8e63009643
+//# debugId=f7058fc6-251e-5e11-af6c-de15f6e256f3

package/package.json

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

package/src/commands/pack-install.ts

@@ -68,6 +68,80 @@ import {
 import { readCache, listSecretCacheScopes } from '../utils/secrets-cache.js';
 import type { PackManifest, PackContributeKey } from '../types.js';
 
+const PACK_UPDATE_CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+const PACK_UPDATE_FETCH_TIMEOUT_MS = 3_000;
+
+interface PackUpdateCacheEntry {
+  latest: string;
+  fetchedAt: number;
+}
+
+interface PackUpdateCacheFile {
+  entries: Record<string, PackUpdateCacheEntry>;
+}
+
+export interface ResolveLatestOptions {
+  forceRefresh?: boolean;
+  now?: number;
+  cacheTtlMs?: number;
+  fetchImpl?: typeof fetch;
+}
+
+const gitLsRemoteMemo = new Map<string, string>();
+
+function packUpdateCachePath(): string {
+  return path.join(os.homedir(), '.hq', 'pack-update-cache.json');
+}
+
+function readPackUpdateCache(): PackUpdateCacheFile {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(packUpdateCachePath(), 'utf-8')) as Partial<PackUpdateCacheFile>;
+    if (!parsed || typeof parsed !== 'object' || !parsed.entries || typeof parsed.entries !== 'object') {
+      return { entries: {} };
+    }
+    return { entries: parsed.entries as Record<string, PackUpdateCacheEntry> };
+  } catch {
+    return { entries: {} };
+  }
+}
+
+function writePackUpdateCache(cache: PackUpdateCacheFile): void {
+  try {
+    const file = packUpdateCachePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cache));
+  } catch {
+    // best-effort; update checks must never fail because the cache is unwritable
+  }
+}
+
+function cachedLatest(cacheKey: string, opts: ResolveLatestOptions): string | undefined {
+  if (opts.forceRefresh) return undefined;
+  const entry = readPackUpdateCache().entries[cacheKey];
+  if (!entry || typeof entry.latest !== 'string' || typeof entry.fetchedAt !== 'number') return undefined;
+  const now = opts.now ?? Date.now();
+  const ttl = opts.cacheTtlMs ?? PACK_UPDATE_CACHE_TTL_MS;
+  return now - entry.fetchedAt <= ttl ? entry.latest : undefined;
+}
+
+function storeCachedLatest(cacheKey: string, latest: string, opts: ResolveLatestOptions): void {
+  const cache = readPackUpdateCache();
+  cache.entries[cacheKey] = { latest, fetchedAt: opts.now ?? Date.now() };
+  writePackUpdateCache(cache);
+}
+
+async function latestWithDiskCache(
+  cacheKey: string,
+  opts: ResolveLatestOptions,
+  refresh: () => Promise<string | undefined> | string | undefined,
+): Promise<string | undefined> {
+  const cached = cachedLatest(cacheKey, opts);
+  if (cached) return cached;
+  const latest = await refresh();
+  if (latest) storeCachedLatest(cacheKey, latest, opts);
+  return latest;
+}
+
 // ---------------------------------------------------------------------------
 // Source classification
 // ---------------------------------------------------------------------------
@@ -676,17 +750,37 @@ function rsyncDir(src: string, dest: string): void {
  */
 function isNamedRef(url: string, ref: string): boolean {
   try {
-    const out = execFileSync(
-      'git',
-      ['ls-remote', '--heads', '--tags', url, ref],
-      { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] },
-    );
+    const out = gitLsRemote(['--heads', '--tags', url, ref]);
     return out.trim().length > 0;
   } catch {
     return false;
   }
 }
 
+function gitLsRemote(args: string[]): string {
+  const key = args.join('\0');
+  const cached = gitLsRemoteMemo.get(key);
+  if (cached !== undefined) return cached;
+  const out = execFileSync(
+    'git',
+    ['ls-remote', ...args],
+    { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] },
+  );
+  gitLsRemoteMemo.set(key, out);
+  return out;
+}
+
+async function fetchLatestNpmVersion(pkg: string, opts: ResolveLatestOptions): Promise<string | undefined> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const res = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(pkg)}/latest`, {
+    headers: { Accept: 'application/json' },
+    signal: AbortSignal.timeout(PACK_UPDATE_FETCH_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`registry returned ${res.status}`);
+  const body = (await res.json()) as { version?: unknown };
+  return typeof body.version === 'string' ? body.version : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Update-availability probe (no install) — used by `hq packs update --check-only`
 // ---------------------------------------------------------------------------
@@ -711,6 +805,10 @@ function gitRefFromSource(source: string): string | undefined {
   return ref;
 }
 
+function isFullGitSha(ref: string): boolean {
+  return /^[0-9a-f]{40}$/i.test(ref);
+}
+
 /**
  * Probe whether a newer version of an already-installed pack is available,
  * WITHOUT fetching or installing. Reuses the same git/npm primitives as the
@@ -720,10 +818,11 @@ function gitRefFromSource(source: string): string | undefined {
  * @param source         the stamped `source:` from the installed package.yaml
  * @param installedVersion the installed pack's manifest `version` (npm compare)
  */
-export function resolveLatest(
+export async function resolveLatest(
   source: string,
   installedVersion?: string,
-): LatestResult {
+  opts: ResolveLatestOptions = {},
+): Promise<LatestResult> {
   let transport: Transport;
   try {
     transport = classify(source);
@@ -755,15 +854,14 @@ export function resolveLatest(
     const current =
       installedVersion ?? (source.lastIndexOf('@') > 0 ? source.slice(source.lastIndexOf('@') + 1) : undefined);
     try {
-      const latest = execFileSync('npm', ['view', pkg, 'version'], {
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'ignore'],
-      }).trim();
+      const latest = await latestWithDiskCache(`npm:${pkg}`, opts, () =>
+        fetchLatestNpmVersion(pkg, opts),
+      );
       const updateAvailable =
         current && latest ? semverGt(latest, current) : null;
       return { transport, current, latest, updateAvailable };
     } catch (e) {
-      return { transport, current, updateAvailable: null, error: `npm view failed: ${(e as Error).message}` };
+      return { transport, current, updateAvailable: null, error: `npm registry check failed: ${(e as Error).message}` };
     }
   }
 
@@ -778,13 +876,12 @@ export function resolveLatest(
   const current = gitRefFromSource(source);
   // If install followed a named ref (branch/tag), compare that ref's tip;
   // otherwise (default SHA-pin) compare the default branch HEAD.
-  const refArg = current && isNamedRef(url, current) ? current : 'HEAD';
+  const refArg = current && !isFullGitSha(current) && isNamedRef(url, current) ? current : 'HEAD';
   try {
-    const out = execFileSync('git', ['ls-remote', url, refArg], {
-      encoding: 'utf-8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-    const latest = out.split(/\s+/)[0] || undefined;
+    const latest = await latestWithDiskCache(`git:${url}#${refArg}`, opts, () => {
+      const out = gitLsRemote([url, refArg]).trim();
+      return out.split(/\s+/)[0] || undefined;
+    });
     const updateAvailable =
       current && latest ? !latest.startsWith(current) && !current.startsWith(latest) : null;
     return { transport, current, latest, updateAvailable };

package/src/commands/pack-update-cache.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+
+vi.mock('child_process', () => ({
+  execFileSync: vi.fn(),
+  spawnSync: vi.fn(() => ({ status: 0 })),
+}));
+
+vi.mock('../utils/vault-api.js', () => ({
+  vaultApiFetchPublic: vi.fn(),
+}));
+
+const tmpHome = path.join(os.tmpdir(), `hq-pack-update-cache-${process.pid}`);
+
+beforeEach(() => {
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  fs.mkdirSync(tmpHome, { recursive: true });
+  vi.stubEnv('HOME', tmpHome);
+  vi.mocked(execFileSync).mockReset();
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+async function loadModule() {
+  vi.resetModules();
+  return await import('./pack-install.js');
+}
+
+describe('resolveLatest pack update cache', () => {
+  it('fetches npm registry metadata over HTTP once, then compares cached latest against the installed version at read time', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: '2.0.0' }),
+    } as unknown as Response);
+    vi.stubGlobal('fetch', fetchMock);
+
+    const { resolveLatest } = await loadModule();
+
+    const staleInstall = await resolveLatest('@scope/pack@1.0.0', '1.0.0', {
+      forceRefresh: true,
+    });
+    const currentInstall = await resolveLatest('@scope/pack@1.0.0', '2.0.0');
+
+    expect(staleInstall).toMatchObject({
+      transport: 'npm',
+      current: '1.0.0',
+      latest: '2.0.0',
+      updateAvailable: true,
+    });
+    expect(currentInstall).toMatchObject({
+      transport: 'npm',
+      current: '2.0.0',
+      latest: '2.0.0',
+      updateAvailable: false,
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(execFileSync)).not.toHaveBeenCalledWith(
+      'npm',
+      ['view', '@scope/pack', 'version'],
+      expect.anything(),
+    );
+    expect(fs.existsSync(path.join(tmpHome, '.hq', 'pack-update-cache.json'))).toBe(true);
+  });
+
+  it('bypasses a fresh npm cache entry when forceRefresh is set', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ version: '2.0.0' }),
+      } as unknown as Response)
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ version: '3.0.0' }),
+      } as unknown as Response);
+    vi.stubGlobal('fetch', fetchMock);
+
+    const { resolveLatest } = await loadModule();
+
+    await resolveLatest('@scope/pack@1.0.0', '1.0.0', { forceRefresh: true });
+    const refreshed = await resolveLatest('@scope/pack@1.0.0', '1.0.0', {
+      forceRefresh: true,
+    });
+
+    expect(refreshed).toMatchObject({
+      latest: '3.0.0',
+      updateAvailable: true,
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('shares git ls-remote probes by URL and ref within one process', async () => {
+    vi.mocked(execFileSync).mockImplementation((_cmd, args) => {
+      const argv = args as string[];
+      if (argv[1] === '--heads') return '';
+      if (argv[0] === 'ls-remote') return 'abcdef1234567890\tHEAD\n';
+      throw new Error(`unexpected command: ${argv.join(' ')}`);
+    });
+
+    const { resolveLatest } = await loadModule();
+
+    const first = await resolveLatest('https://example.test/repo.git#123456', '1.0.0');
+    const second = await resolveLatest('https://example.test/repo.git#123456', '1.0.0');
+
+    expect(first.latest).toBe('abcdef1234567890');
+    expect(second.latest).toBe('abcdef1234567890');
+    const lsRemoteCalls = vi
+      .mocked(execFileSync)
+      .mock.calls.filter(([cmd, args]) => cmd === 'git' && (args as string[])[0] === 'ls-remote');
+    expect(lsRemoteCalls).toHaveLength(2);
+  });
+
+  it('uses a fresh git disk cache entry without probing git for SHA-pinned sources', async () => {
+    const installedSha = '1111111111111111111111111111111111111111';
+    vi.mocked(execFileSync).mockImplementation((_cmd, args) => {
+      const argv = args as string[];
+      if (argv[0] === 'ls-remote') return 'abcdef1234567890\tHEAD\n';
+      throw new Error(`unexpected command: ${argv.join(' ')}`);
+    });
+
+    const firstModule = await loadModule();
+    await firstModule.resolveLatest(`https://example.test/repo.git#${installedSha}`, '1.0.0', {
+      forceRefresh: true,
+    });
+
+    vi.mocked(execFileSync).mockReset();
+    const secondModule = await loadModule();
+    const cached = await secondModule.resolveLatest(
+      `https://example.test/repo.git#${installedSha}`,
+      '1.0.0',
+    );
+
+    expect(cached).toMatchObject({
+      transport: 'git',
+      current: installedSha,
+      latest: 'abcdef1234567890',
+      updateAvailable: true,
+    });
+    expect(vi.mocked(execFileSync)).not.toHaveBeenCalled();
+  });
+});

package/src/commands/packs.ts

@@ -144,6 +144,7 @@ export function buildInstalledView(
   pack: InstalledPack,
   installedSources: Set<string>,
   checkUpdates: boolean,
+  latestProbe?: LatestResult,
 ): InstalledPackView {
   if (!pack.manifest) {
     return {
@@ -178,7 +179,7 @@ export function buildInstalledView(
 
   let updateAvailable: boolean | null = null;
   if (checkUpdates && m.source) {
-    updateAvailable = resolveLatest(m.source, m.version).updateAvailable;
+    updateAvailable = latestProbe?.updateAvailable ?? null;
   }
 
   // US-005 — surface the pack's `initialization` block so the HQ Sync
@@ -214,15 +215,27 @@ export function buildInstalledView(
   };
 }
 
-function buildListView(hqRoot: string, checkUpdates: boolean, evalConditionals: boolean): PacksListView {
+async function buildListView(
+  hqRoot: string,
+  checkUpdates: boolean,
+  evalConditionals: boolean,
+  refreshUpdates: boolean,
+): Promise<PacksListView> {
   const hqVersion = readHqVersion(hqRoot);
   const packs = listInstalledPacks(hqRoot);
   const catalog = readRecommendedPackages(hqRoot);
   const catalogSources = new Set(catalog.map((c) => c.source));
   const warnings: string[] = [];
 
-  const installed = packs.map((p) =>
-    buildInstalledView(hqRoot, hqVersion, p, catalogSources, checkUpdates),
+  const latestProbes = await Promise.all(
+    packs.map((p) =>
+      checkUpdates && p.manifest?.source
+        ? resolveLatest(p.manifest.source, p.manifest.version, { forceRefresh: refreshUpdates })
+        : Promise.resolve(undefined),
+    ),
+  );
+  const installed = packs.map((p, i) =>
+    buildInstalledView(hqRoot, hqVersion, p, catalogSources, checkUpdates, latestProbes[i]),
   );
   for (const p of installed) {
     if (p.error) warnings.push(`${p.name}: ${p.error}`);
@@ -303,6 +316,7 @@ interface UpdateCheck {
 
 interface UpdateOpts extends CommonOpts {
   checkOnly?: boolean;
+  refresh?: boolean;
   yes?: boolean;
   allowHooks?: boolean;
   allowMcp?: boolean;
@@ -334,7 +348,7 @@ async function runUpdate(name: string | undefined, opts: UpdateOpts): Promise<Up
     const probe: LatestResult =
       safeClassify(source) === 'marketplace'
         ? await resolveLatestMarketplace(source, m.version)
-        : resolveLatest(source, m.version);
+        : await resolveLatest(source, m.version, { forceRefresh: true });
     const base: UpdateCheck = {
       name: pname,
       transport: probe.transport,
@@ -517,11 +531,17 @@ export function registerPacksCommand(parent: Command): void {
     .option('--json', 'Machine-readable JSON output')
     .option('--hq-root <path>', 'HQ root (default: auto-detect)')
     .option('--check-updates', 'Probe each pack for available updates (network I/O)')
+    .option('--refresh', 'Bypass cached update probes')
     .option('--eval-conditionals', 'Evaluate catalog conditional predicates (runs bash)')
     .action(
-      async (opts: CommonOpts & { checkUpdates?: boolean; evalConditionals?: boolean }) => {
+      async (opts: CommonOpts & { checkUpdates?: boolean; evalConditionals?: boolean; refresh?: boolean }) => {
         try {
-          const view = buildListView(resolveRoot(opts), !!opts.checkUpdates, !!opts.evalConditionals);
+          const view = await buildListView(
+            resolveRoot(opts),
+            !!opts.checkUpdates,
+            !!opts.evalConditionals,
+            !!opts.refresh,
+          );
           if (wantsJson(opts)) emitJson(view);
           else printListHuman(view);
         } catch (e) {
@@ -537,6 +557,7 @@ export function registerPacksCommand(parent: Command): void {
     .option('--json', 'Machine-readable JSON output')
     .option('--hq-root <path>', 'HQ root (default: auto-detect)')
     .option('--check-only', 'Report availability without installing')
+    .option('--refresh', 'Bypass cached update probes (update refreshes by default)')
     .option('-y, --yes', 'Non-interactive (implies --allow-hooks and --allow-mcp)')
     .option('--allow-hooks', 'Install pack hooks without prompting')
     .option('--allow-mcp', 'Register pack MCP servers without prompting')