@indigoai-us/hq-cli 5.60.0 → 5.62.0

package/src/main.ts

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+
+/**
+ * HQ CLI - Module management, package management, and cloud sync for HQ
+ */
+
+// MUST be first: guard the Node version before any dependency that needs a
+// Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
+import "./node-preflight.js";
+import { Command } from "commander";
+import { initSentry, Sentry } from "./sentry.js";
+import { registerAddCommand } from "./commands/add.js";
+import { registerSyncCommand } from "./commands/sync.js";
+import { registerListCommand } from "./commands/list.js";
+import { registerUpdateCommand } from "./commands/update.js";
+import { registerCloudCommands } from "./commands/cloud.js";
+import { registerSyncModeCommand } from "./commands/sync-mode.js";
+import { registerSyncNarrowCommand } from "./commands/sync-narrow.js";
+import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
+import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
+import { registerLoginCommand } from "./commands/login.js";
+import { registerLogoutCommand } from "./commands/logout.js";
+import { registerWhoamiCommand } from "./commands/whoami.js";
+import { registerOnboardCommand } from "./commands/onboard.js";
+import { registerPackageInstallCommand } from "./commands/pkg-install.js";
+import { registerPackageRemoveCommand } from "./commands/pkg-remove.js";
+import { registerPackageUpdateCommand } from "./commands/pkg-update.js";
+import { registerPackageListCommand } from "./commands/pkg-list.js";
+import { registerPacksCommand } from "./commands/packs.js";
+import { registerPublishCommand } from "./commands/publish.js";
+import { registerCreatorsCommand } from "./commands/creators.js";
+import { registerTeamSyncCommand } from "./commands/team-sync.js";
+import { registerAuthCommands } from "./commands/auth.js";
+import { registerApiKeysCommand } from "./commands/api-keys.js";
+import { registerSecretsCommand } from "./commands/secrets.js";
+import { registerRunCommand } from "./commands/run.js";
+import { registerGroupsCommand } from "./commands/groups.js";
+import { registerWorkersCommand } from "./commands/workers.js";
+import { registerGroupGrantsCommand } from "./commands/group-grants.js";
+import { registerFilesCommand } from "./commands/files.js";
+import { registerFilesBrowseCommands } from "./commands/files-browse.js";
+import { registerSkillCommand } from "./commands/skill.js";
+import { registerMembersCommand } from "./commands/members.js";
+import { registerPeopleCommand } from "./commands/people.js";
+import { registerDmCommand } from "./commands/dm.js";
+import { registerChannelsCommand } from "./commands/channels.js";
+import { registerFeedbackCommand } from "./commands/feedback.js";
+import { registerMeetingsCommand } from "./commands/meetings.js";
+import { registerSourcesCommand } from "./commands/sources.js";
+import { registerSignalsCommand } from "./commands/signals.js";
+import { registerIntegrationsCommand } from "./commands/integrations.js";
+import { registerReindexCommand } from "./commands/reindex.js";
+import { registerRescueCommand } from "./commands/rescue.js";
+import { registerMcpCommand } from "./commands/mcp-status.js";
+import { registerCrmCommand } from "./commands/crm.js";
+import { registerCompanyCommand } from "./commands/company.js";
+import { registerAgentsCommand } from "./commands/agents.js";
+import { registerOutpostsCommand } from "./commands/outposts.js";
+import { registerDbCommand } from "./commands/db.js";
+import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
+import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { isEpipe } from "./utils/epipe.js";
+import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
+import {
+  maybeWarnNewVersion,
+  refreshVersionCache,
+} from "./utils/version-check.js";
+import {
+  enforceVersionGate,
+  shouldSkipGate,
+} from "./utils/version-gate.js";
+import { CLI_VERSION } from "./cli-version.js";
+
+// Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
+// the pipe early. This covers the ASYNC path — an 'error' event emitted on the
+// stream. The SYNCHRONOUS path (a `write EPIPE` thrown straight out of
+// console.log inside a command) is handled in the top-level catch below; both
+// share `isEpipe` (HQ-6B).
+const onPipeError = (err: NodeJS.ErrnoException): void => {
+  if (isEpipe(err)) {
+    process.exit(0);
+  }
+  throw err;
+};
+process.stdout.on("error", onPipeError);
+process.stderr.on("error", onPipeError);
+
+initSentry();
+maybeWarnNewVersion();
+
+const program = new Command();
+
+program
+  .name("hq")
+  .description("HQ management CLI — modules, packages, and cloud sync")
+  .version(CLI_VERSION);
+
+// Module management subcommand group
+const modulesCmd = program
+  .command("modules")
+  .description("Module management commands");
+
+registerAddCommand(modulesCmd);
+registerSyncCommand(modulesCmd);
+registerListCommand(modulesCmd);
+registerUpdateCommand(modulesCmd);
+
+// Package management subcommand group
+const packagesCmd = program
+  .command("packages")
+  .description("Package management commands");
+
+registerPackageInstallCommand(packagesCmd);
+registerPackageRemoveCommand(packagesCmd);
+registerPackageUpdateCommand(packagesCmd);
+registerPackageListCommand(packagesCmd);
+
+// Content-pack lifecycle (core/packages/hq-pack-*). Distinct from the registry
+// `packages` system above. Available as both `hq packages packs …` (grouped)
+// and `hq packs …` (top-level convenience).
+registerPacksCommand(packagesCmd);
+registerPacksCommand(program);
+
+// Top-level shortcuts for package commands
+// "hq install <slug>" = "hq packages install <slug>"
+// "hq remove <slug>"  = "hq packages remove <slug>"
+registerPackageInstallCommand(program);
+registerPackageRemoveCommand(program);
+
+// Marketplace publish (top-level — packer + authenticated upload, US-004)
+// "hq publish <skill-or-worker-path>" packages and submits a pack to the
+// marketplace via POST /v1/listings.
+registerPublishCommand(program);
+// `hq creators apply` — request verified-creator access (required to publish).
+registerCreatorsCommand(program);
+
+// Cloud sync subcommand group
+const syncCmd = program
+  .command("sync")
+  .description("Cloud sync commands — sync HQ to S3 for mobile access");
+
+registerCloudCommands(syncCmd);
+registerSyncModeCommand(syncCmd);
+registerSyncNarrowCommand(syncCmd);
+
+// Cloud provisioning subcommand group (entity + bucket + initial sync)
+// Distinct from `hq sync` which assumes provisioning has already happened.
+const cloudCmd = program
+  .command("cloud")
+  .description(
+    "Cloud commands — provision entities and manage cloud-backed companies",
+  );
+
+registerCloudProvisionCommands(cloudCmd);
+registerCloudDemoteCommands(cloudCmd);
+
+// Team commands (top-level)
+registerTeamSyncCommand(program);
+
+// Auth commands (top-level — Cognito OAuth)
+registerLoginCommand(program);
+registerLogoutCommand(program);
+registerWhoamiCommand(program);
+registerAuthCommands(program);
+
+// Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
+registerSecretsCommand(program);
+
+// Vault databases (subcommand group — hq db status|sql|migrate|provision)
+registerDbCommand(program);
+
+// API key management (subcommand group — hq api-keys create|list|revoke)
+registerApiKeysCommand(program);
+
+// Schema-driven dev runner — hq run [options] -- <cmd>
+registerRunCommand(program);
+
+// Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
+registerGroupsCommand(program);
+
+// Worker discovery + sharing (subcommand group — hq workers list|share)
+registerWorkersCommand(program);
+
+// Cross-company group grants (subcommand group —
+// hq group-grants grant|revoke|outbound|inbound)
+registerGroupGrantsCommand(program);
+
+// Files ACL management (subcommand group — hq files share|unshare|acl)
+// `registerFilesCommand` returns the `files` group so we can attach the
+// browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
+const filesCmd = registerFilesCommand(program);
+registerFilesBrowseCommands(filesCmd);
+
+// Skill collaboration loop (subcommand group — hq skill suggest|list-suggestions|review).
+// A thin terminal front-end over the SAME wired hq-pro skill suggestion + merge
+// routes the MCP (US-007) and console merge (US-009) surfaces use — no forked logic.
+registerSkillCommand(program);
+
+// Membership management (subcommand group — hq members invite|list|revoke)
+registerMembersCommand(program);
+// People directory (subcommand group — hq people list|search|resolve), reading
+// the local companies/<co>/people store scoped to one company.
+registerPeopleCommand(program);
+registerDmCommand(program);
+registerChannelsCommand(program);
+
+// Onboarding (top-level — Cognito + vault-service provisioning)
+registerOnboardCommand(program);
+
+// Feedback (subcommand group — hq feedback bug|feature)
+registerFeedbackCommand(program);
+
+// Meetings (subcommand group — hq meetings list|get|search|transcript|notes)
+registerMeetingsCommand(program);
+
+// Sources read surface (subcommand group — hq sources list|get|channels|entities)
+registerSourcesCommand(program);
+
+// Signals read surface (subcommand group — hq signals list|get|types|entities)
+registerSignalsCommand(program);
+
+// Company-connected apps via the governed integration gateway
+// (subcommand group — hq integrations list|tools|call|approve|reject)
+registerIntegrationsCommand(program);
+
+// Skill/personal-overlay mirroring + workers-registry regen. Invoked by the
+// hq-core reindex hook shim (Stop / PostToolUse) and by sync()/rescue() after
+// they change on-disk sources. Keeps a `master-sync` alias for one release.
+// Implementation lives in @indigoai-us/hq-cloud.
+registerReindexCommand(program);
+
+// Drift-preserving HQ-core re-sync (top-level — `hq rescue`). CLI sibling of
+// the HQ Sync app's "Update / Restore" pill; drives the same replace-rescue.sh
+// shipped from @indigoai-us/hq-cloud.
+registerRescueCommand(program);
+
+// MCP pack observability (subcommand group — `hq mcp status`). Read-only
+// provenance-based status across BOTH Claude + Codex runtimes (reads `_hqPack`
+// off the configs, NOT linkStatus), with secret-redacted output + `--json`.
+registerMcpCommand(program);
+
+// Native CRM entity upsert (subcommand group — `hq crm entity upsert`). Wraps
+// POST /crm/entities (the ontology write gate) so an authenticated company
+// member can create/update canonical CRM entities in the company vault.
+registerCrmCommand(program);
+
+// Company settings (subcommand group — `hq company settings set`). Owner-only
+// toggles for crmEnabled / ontologyEnabled via PUT /company-settings.
+registerCompanyCommand(program);
+
+// Cloud agent management (subcommand group — `hq agents …`). Rename, reconfigure,
+// start/stop, and tear down a company's fleet agents via the hq-pro /v1/agents
+// control plane — the same routes the web console's agents panel calls.
+registerAgentsCommand(program);
+
+// Personal Outpost management (subcommand group — `hq outposts …`). List, inspect,
+// enable Codex on, refresh login for, and destroy your EC2 boxes via the hq-pro
+// /outpost/* control plane.
+registerOutpostsCommand(program);
+
+export async function runCli(): Promise<void> {
+  try {
+    Sentry.addBreadcrumb({
+      category: "command",
+      message: sanitizeArgv(process.argv.slice(2)).join(" "),
+      level: "info",
+    });
+    // Hard version gate: ask hq-pro whether this CLI is below the floor and
+    // auto-update if so (exits the process on update). Skipped for inspection
+    // flags (`--version`, `--help`) so users debugging a broken install can
+    // still introspect what they have. Silent on any failure — never blocks
+    // the CLI on a flaky network or hq-pro hiccup. See `utils/version-gate.ts`.
+    if (!shouldSkipGate(process.argv)) {
+      await enforceVersionGate();
+    }
+    await program.parseAsync();
+  } catch (err) {
+    // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
+    // (`hq … | head`, `source <(hq …)`, a parent that exited). That is normal
+    // Unix behavior with no user-facing degradation — exit cleanly (0) and
+    // skip Sentry capture instead of shipping a fatal (HQ-6B). A synchronous
+    // `write EPIPE` thrown out of console.log lands here rather than on the
+    // stream 'error' listener above.
+    if (isEpipe(err)) {
+      process.exitCode = 0;
+    } else if (isInterceptedProcessExit(err)) {
+      // A security/audit FUZZ harness replaced `process.exit` with a throw so it
+      // can keep exercising the binary. Commander calling `process.exit` for
+      // normal CLI control flow (e.g. an unknown command → exit 1) then surfaces
+      // here as that synthetic marker. It is a test-harness artifact, NOT an
+      // hq-cli defect — a real user's `process.exit` just exits, so nothing is
+      // thrown or captured. Skip Sentry capture (no signal, no user-facing
+      // degradation) and preserve the intended non-zero exit (HQ-CLI-3).
+      process.exitCode = 1;
+    } else {
+      // A full disk / exhausted quota / read-only filesystem is the user's
+      // machine, not an HQ code defect. Surface a clear, actionable message and
+      // skip Sentry capture so one full disk doesn't flood the tracker with
+      // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
+      // to Sentry and still exit 1.
+      const envMsg = environmentalFsErrorMessage(err);
+      if (envMsg) {
+        process.stderr.write(`hq: ${envMsg}\n`);
+      } else {
+        Sentry.captureException(err);
+      }
+      process.exitCode = 1;
+    }
+  } finally {
+    // Release health: finalize the per-run session before the flush.
+    Sentry.endSession();
+    await Promise.allSettled([refreshVersionCache(), Sentry.flush(2000)]);
+  }
+}

package/src/utils/cognito-session.ts

@@ -57,7 +57,7 @@ export const DEFAULT_COGNITO: CognitoAuthConfig = {
 };
 
 export const DEFAULT_VAULT_API_URL =
-  process.env.HQ_VAULT_API_URL ?? "https://hqapi.getindigo.ai";
+  process.env.HQ_VAULT_API_URL ?? "https://hqapi.hq.computer";
 
 /**
  * Resolve the HQ tree root for cloud-aware subcommands (`hq sync`, `hq onboard`,

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

@@ -39,6 +39,100 @@ describe("SandboxRunnerClient", () => {
     });
   });
 
+  it("retries startJob after fetch rejects twice then succeeds", async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockRejectedValueOnce(new TypeError("fetch failed"))
+      .mockRejectedValueOnce(new Error("ECONNRESET"))
+      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }));
+    const sleep = vi.fn(async () => {});
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+      sleep,
+    });
+
+    await expect(
+      client.startJob("jwt-token", {
+        companyUid: "cmp_123",
+        secretNames: ["API_KEY"],
+        command: "node script.js",
+      }),
+    ).resolves.toEqual({ jobId: "job_1", status: "queued" });
+    expect(fetchImpl).toHaveBeenCalledTimes(3);
+    expect(sleep).toHaveBeenCalledTimes(2);
+  });
+
+  it("retries startJob after a retryable 503 response", async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(jsonRes({ message: "warming up" }, 503))
+      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }));
+    const sleep = vi.fn(async () => {});
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+      sleep,
+    });
+
+    await expect(
+      client.startJob("jwt-token", {
+        companyUid: "cmp_123",
+        secretNames: ["API_KEY"],
+        command: "node script.js",
+      }),
+    ).resolves.toEqual({ jobId: "job_1", status: "queued" });
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+    expect(sleep).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([400, 401])("does not retry startJob on %i responses", async (status) => {
+    const fetchImpl = vi.fn<typeof fetch>(async () =>
+      jsonRes({ message: "bad request" }, status),
+    );
+    const sleep = vi.fn(async () => {});
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+      sleep,
+    });
+
+    await expect(
+      client.startJob("jwt-token", {
+        companyUid: "cmp_123",
+        secretNames: ["API_KEY"],
+        command: "node script.js",
+      }),
+    ).rejects.toThrow("Sandbox Runner rejected job: bad request");
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(sleep).not.toHaveBeenCalled();
+  });
+
+  it("throws a clear exhaustion error after maxAttempts transient failures", async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockRejectedValue(new TypeError("fetch failed"));
+    const sleep = vi.fn(async () => {});
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+      retry: { maxAttempts: 3 },
+      sleep,
+    });
+
+    await expect(
+      client.startJob("jwt-token", {
+        companyUid: "cmp_123",
+        secretNames: ["API_KEY"],
+        command: "node script.js",
+      }),
+    ).rejects.toThrow(
+      "Sandbox Runner did not respond after 3 attempts (cold start or transient network); last error: fetch failed",
+    );
+    expect(fetchImpl).toHaveBeenCalledTimes(3);
+    expect(sleep).toHaveBeenCalledTimes(2);
+  });
+
   it("polls queued and running states until succeeded", async () => {
     const fetchImpl = vi
       .fn<typeof fetch>()
@@ -77,6 +171,40 @@ describe("SandboxRunnerClient", () => {
     );
   });
 
+  it("tolerates one transient fetch rejection while polling", async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }))
+      .mockRejectedValueOnce(new TypeError("fetch failed"))
+      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "running" }))
+      .mockResolvedValueOnce(
+        jsonRes({
+          jobId: "job_1",
+          status: "succeeded",
+          output: "ok\n",
+          exitCode: 0,
+          success: true,
+        }),
+      );
+    const sleep = vi.fn(async () => {});
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+      sleep,
+    });
+
+    await expect(
+      client.pollJob("jwt-token", "job_1", { intervalMs: 0 }),
+    ).resolves.toMatchObject({
+      jobId: "job_1",
+      status: "succeeded",
+      output: "ok\n",
+      exitCode: 0,
+      success: true,
+    });
+    expect(fetchImpl).toHaveBeenCalledTimes(4);
+  });
+
   it("returns failed terminal jobs with error details", async () => {
     const fetchImpl = vi.fn<typeof fetch>(async () =>
       jsonRes({

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

@@ -22,6 +22,8 @@ export interface SandboxRunnerJob {
 export interface SandboxRunnerClientOptions {
   baseUrl?: string;
   fetchImpl?: typeof fetch;
+  retry?: SandboxRunnerRetryOptions;
+  sleep?: (ms: number) => Promise<void>;
 }
 
 export interface SandboxRunnerPollOptions {
@@ -29,7 +31,21 @@ export interface SandboxRunnerPollOptions {
   maxPolls?: number;
 }
 
-const DEFAULT_SANDBOX_RUNNER_URL = "https://hqapi.getindigo.ai/sandbox";
+export interface SandboxRunnerRetryOptions {
+  maxAttempts?: number;
+  maxElapsedMs?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+}
+
+const DEFAULT_SANDBOX_RUNNER_URL = "https://hqapi.hq.computer/sandbox";
+const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
+const DEFAULT_RETRY_OPTIONS: Required<SandboxRunnerRetryOptions> = {
+  maxAttempts: 8,
+  maxElapsedMs: 90_000,
+  baseDelayMs: 500,
+  maxDelayMs: 5_000,
+};
 
 function normalizeBaseUrl(baseUrl: string): string {
   return baseUrl.replace(/\/+$/, "");
@@ -82,20 +98,100 @@ function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return String(error);
+}
+
+function parseRetryAfterMs(value: string | null): number | undefined {
+  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 {
   private readonly baseUrl: string;
   private readonly fetchImpl: typeof fetch;
+  private readonly retry: Required<SandboxRunnerRetryOptions>;
+  private readonly sleep: (ms: number) => Promise<void>;
 
   constructor(options: SandboxRunnerClientOptions = {}) {
     this.baseUrl = normalizeBaseUrl(options.baseUrl ?? getSandboxRunnerBaseUrl());
     this.fetchImpl = options.fetchImpl ?? fetch;
+    this.retry = { ...DEFAULT_RETRY_OPTIONS, ...options.retry };
+    this.sleep = options.sleep ?? delay;
+  }
+
+  private async fetchWithRetry(
+    url: string,
+    init: RequestInit,
+  ): Promise<Response> {
+    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}`,
+    );
+  }
+
+  private shouldRetry(attempt: number, startedAt: number): boolean {
+    if (attempt >= this.retry.maxAttempts) {
+      return false;
+    }
+    return Date.now() - startedAt < this.retry.maxElapsedMs;
+  }
+
+  private nextDelayMs(attempt: number, res?: Response): number {
+    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: string,
     request: SandboxRunnerStartRequest,
   ): Promise<SandboxRunnerStartResponse> {
-    const res = await this.fetchImpl(`${this.baseUrl}/jobs`, {
+    const res = await this.fetchWithRetry(`${this.baseUrl}/jobs`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${token}`,
@@ -124,7 +220,7 @@ export class SandboxRunnerClient {
   }
 
   async getJob(token: string, jobId: string): Promise<SandboxRunnerJob> {
-    const res = await this.fetchImpl(
+    const res = await this.fetchWithRetry(
       `${this.baseUrl}/jobs/${encodeURIComponent(jobId)}`,
       {
         headers: { Authorization: `Bearer ${token}` },
@@ -155,7 +251,7 @@ 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.`);
   }

package/src/utils/version-check.test.ts

@@ -120,6 +120,36 @@ describe("refreshVersionCache", () => {
     expect(typeof written.fetchedAt).toBe("number");
   });
 
+  it("returns without fetching when the cached version is still within the TTL", async () => {
+    writeCache("5.99.0", 60 * 1000);
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+
+    const mod = await loadModule();
+    await mod.refreshVersionCache();
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    const cachePath = path.join(tmpHome, ".hq", "version-check.json");
+    const written = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+    expect(written.latest).toBe("5.99.0");
+  });
+
+  it("skips passive refresh for noninteractive status probes", async () => {
+    const originalArgv = process.argv;
+    process.argv = ["node", "hq", "mcp", "status", "--json"];
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+
+    try {
+      const mod = await loadModule();
+      await mod.refreshVersionCache();
+    } finally {
+      process.argv = originalArgv;
+    }
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("does not throw or write a cache when fetch fails", async () => {
     const fetchMock = vi.fn().mockRejectedValue(new Error("network down"));
     vi.stubGlobal("fetch", fetchMock);