@indigoai-us/hq-cli 5.108.4 → 5.108.6

package/dist/utils/self-update.d.ts

@@ -71,6 +71,15 @@ export type SelfUpdateAction =
  | "update-failed"
 /** Updated, but the re-exec couldn't start; continue on the current (in-memory) version. */
  | "updated-no-reexec"
+/**
+ * The install reported success but the `hq` on PATH still resolves the old
+ * version (a shadowing/ghost install, a prefix/PATH mismatch, or a stale
+ * tarball). Re-installing the same target can never converge, so we do NOT
+ * re-exec, we record the target as ineffective so the startup path stops
+ * auto-retrying it, and the command runs on the current version. This is the
+ * guard against the self-update loop.
+ */
+ | "update-ineffective"
 /** Updated and the command re-ran on the new version; exit with `reexecStatus`. */
  | "reexec"
 /**
@@ -127,6 +136,17 @@ export interface SelfUpdateDeps {
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
     reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
     acquireLock?: () => (() => void) | null;
+    /**
+     * Read-your-writes convergence check run after a "successful" install:
+     * returns false only when the `hq` on PATH still resolves a build older than
+     * the target we just installed. Defaults to {@link checkUpdateConvergence}.
+     */
+    checkConvergence?: (targetVersion: string) => boolean;
+    /**
+     * Persist that `version` installed but never took effect, so the startup path
+     * stops auto-retrying it. Defaults to {@link markLatestIneffective}.
+     */
+    markIneffective?: (version: string) => void;
     /**
      * Whether a human is watching this invocation. Defaults to "stderr is a TTY",
      * which is false for exactly the callers that must not replace the CLI

package/dist/utils/self-update.js

@@ -60,8 +60,9 @@ import { spawnSync } from "node:child_process";
 import semver from "semver";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
-import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, inOwnProcessGroup, isLocalDependencyInstall, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, checkUpdateConvergence, inOwnProcessGroup, isLocalDependencyInstall, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
+import { markLatestIneffective } from "./version-check.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
  * One update + one re-exec per user invocation, ever.
@@ -278,6 +279,26 @@ async function updateAndReexec(argv, flavor, known, deps) {
         console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
         return { action: "update-failed", latest };
     }
+    // Read-your-writes: a "successful" `npm install -g` proves only that the
+    // prefix was rewritten, NOT that the `hq` this user's PATH resolves is the
+    // copy we just wrote. When a ghost/shadowing install keeps winning PATH
+    // resolution (or a prefix/PATH mismatch or stale tarball leaves the running
+    // copy behind), re-exec'ing here runs the command on the SAME stale version,
+    // and — because `staleAgainstCachedLatest` still sees the baked CLI_VERSION
+    // as behind `latest` — the next invocation installs and re-execs again,
+    // forever. The hard version gate already verifies convergence; the soft
+    // startup path did not, which is the 5.105.0 → 5.105.1 self-update loop.
+    //
+    // So verify before announcing success. On non-convergence: mark the target
+    // ineffective (suppresses auto-retry for a cooldown), skip the pointless
+    // re-exec into a stale copy, and let the command run on the current version.
+    const checkConvergence = deps.checkConvergence ?? checkUpdateConvergence;
+    const converged = checkConvergence(latestValid);
+    if (converged === false) {
+        (deps.markIneffective ?? markLatestIneffective)(latest);
+        console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
+        return { action: "update-ineffective", latest };
+    }
     const childEnv = { ...env, [REEXEC_GUARD_ENV]: "1" };
     const status = (deps.reexec ?? reexecHq)([...argv.slice(2)], childEnv);
     if (status === null) {

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

@@ -10,6 +10,13 @@ declare function isKnownNoninteractiveStatusProbe(argv?: readonly string[]): boo
  * command, and warns only if that fails.
  */
 export declare function staleAgainstCachedLatest(now?: number): string | null;
+/**
+ * Record that installing `version` did not move the on-PATH `hq` forward, so
+ * {@link staleAgainstCachedLatest} stops auto-retrying it for a cooldown. Called
+ * by the self-updater's convergence check. Best-effort: a write failure only
+ * 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 declare const __test__: {
     CACHE_TTL_MS: number;

package/dist/utils/version-check.js

@@ -9,6 +9,12 @@ 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;
+/**
+ * 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
+ * whose PATH is later fixed recovers on its own without a manual `hq rescue`.
+ */
+const INEFFECTIVE_COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6h
 function cachePath() {
     return path.join(os.homedir(), ".hq", "version-check.json");
 }
@@ -26,7 +32,16 @@ function readCache() {
             typeof parsed.fetchedAt !== "number") {
             return null;
         }
-        return { latest: parsed.latest, fetchedAt: parsed.fetchedAt };
+        return {
+            latest: parsed.latest,
+            fetchedAt: parsed.fetchedAt,
+            ...(typeof parsed.ineffectiveLatest === "string"
+                ? { ineffectiveLatest: parsed.ineffectiveLatest }
+                : {}),
+            ...(typeof parsed.ineffectiveAt === "number"
+                ? { ineffectiveAt: parsed.ineffectiveAt }
+                : {}),
+        };
     }
     catch {
         return null;
@@ -119,8 +134,38 @@ export function staleAgainstCachedLatest(now = Date.now()) {
         return null;
     if (!semver.gt(latest, current))
         return null;
+    // Loop guard: a previous self-update installed this exact `latest` but the
+    // on-PATH `hq` never converged to it (see markLatestIneffective). Retrying
+    // the same target re-installs it and re-execs into the same stale copy on
+    // every invocation without ever making progress, so suppress it for a
+    // cooldown. A newer `latest` (different target) is never suppressed.
+    if (entry.ineffectiveLatest === entry.latest &&
+        typeof entry.ineffectiveAt === "number" &&
+        now - entry.ineffectiveAt <= INEFFECTIVE_COOLDOWN_MS) {
+        return null;
+    }
     return entry.latest;
 }
+/**
+ * Record that installing `version` did not move the on-PATH `hq` forward, so
+ * {@link staleAgainstCachedLatest} stops auto-retrying it for a cooldown. Called
+ * by the self-updater's convergence check. Best-effort: a write failure only
+ * means the loop guard is skipped this once, never a broken CLI.
+ */
+export function markLatestIneffective(version, now = Date.now()) {
+    const entry = readCache();
+    if (!entry)
+        return;
+    // Only mark the target we actually believe is `latest`; marking anything else
+    // would risk suppressing a legitimately newer release.
+    if (entry.latest !== version)
+        return;
+    writeCache({
+        ...entry,
+        ineffectiveLatest: version,
+        ineffectiveAt: now,
+    });
+}
 export async function refreshVersionCache() {
     if (isOptedOut())
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.108.4",
+  "version": "5.108.6",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -31,7 +31,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.16.6",
+    "@indigoai-us/hq-cloud": "~6.16.11",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",