@indigoai-us/hq-cli 5.106.1 → 5.106.2

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [5.106.2] — 2026-09-02
+
+### Fixed
+
+- An `hq` installed as a local project dependency no longer updates itself in an
+  endless loop. The updater used to treat a pnpm virtual store
+  (`node_modules/.pnpm/...`) as an npm install prefix and install there — a
+  directory nothing on PATH ever reads — then report success, so the next
+  command found the same old build and updated again. On one outpost this ran
+  `npm install -g` up to 31 times an hour for days. Such copies are now
+  identified as local, reported with the path to fix, and left for their owning
+  project to update.
+- The updater refuses an "update" to a version that is not newer than the one
+  already installed, instead of reinstalling it on every invocation.
+- Success is now reported only after verifying the new version is the one PATH
+  actually resolves. An install that lands somewhere the running `hq` never
+  reads is reported as a failed update rather than as a success.
+
 ## [5.106.1] — 2026-09-02
 
 ## [5.106.0] — 2026-09-02

package/dist/utils/cli-telemetry.js

@@ -33,6 +33,7 @@ async function emitCachedCliSessionStarted() {
                             app: "hq-cli",
                             source: "cli",
                             occurredAt: new Date().toISOString(),
+                            consentBasis: "no-consent",
                             schemaVersion: 1,
                             properties: { version: CLI_VERSION },
                         },

package/dist/utils/self-update.js

@@ -60,7 +60,7 @@ 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, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, inOwnProcessGroup, isLocalDependencyInstall, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
@@ -222,11 +222,20 @@ async function updateAndReexec(argv, flavor, known, deps) {
     if (!interactive && flavor.onlyWhenAttended) {
         return { action: "deferred", latest };
     }
+    // A local copy (a project dependency, a `pnpm dlx` cache) has no self-update
+    // path: every install argv here targets a GLOBAL install, so the copy that is
+    // actually running would stay exactly as stale as it started while the CLI
+    // reported success and re-exec'd into the same build. That is the shape of
+    // the 2026-09-02 gate loop — see isLocalDependencyInstall in version-gate.ts.
+    const install = (deps.resolveInstall ?? resolveRunningInstall)();
+    if (isLocalDependencyInstall(install)) {
+        console.error(chalk.dim(`hq-cli ${latest} is available, but this copy is a local dependency (${install.packageRoot}) — update the project that owns it.`));
+        return { action: "skipped", latest };
+    }
     const releaseLock = flavor.lock ? (deps.acquireLock ?? acquireUpdateLock)() : () => { };
     if (!releaseLock)
         return { action: "skipped", latest };
     let result;
-    const install = (deps.resolveInstall ?? resolveRunningInstall)();
     const plan = buildSelfUpdatePlan(install);
     // A pnpm global install needs PNPM_HOME to find its global bin dir. A
     // minimal-environment parent (systemd, cron, non-login shell) lacks it and

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

@@ -70,6 +70,59 @@ export declare function npmPrefixFromPackageDir(pkgDir: string): string | null;
 export declare function isPnpmManagedPackageDir(pkgDir: string): boolean;
 /** Whether the running package lives inside Bun's global install tree. */
 export declare function isBunManagedPackageDir(pkgDir: string): boolean;
+/**
+ * Whether the package dir sits inside a pnpm **virtual store** — the adjacent
+ * `node_modules/.pnpm` segment pair pnpm creates for every install, global or
+ * not:
+ *
+ *   <proj>/node_modules/.pnpm/@indigoai-us+hq-cli@5.69.0/node_modules/@indigoai-us/hq-cli
+ *
+ * A virtual store is a content-addressed cache keyed by the EXACT version in
+ * the directory name. Nothing on PATH ever resolves through
+ * `<store>/lib/node_modules`, and the store dir is not an npm prefix — so the
+ * one thing that must never happen is treating it as one.
+ *
+ * Note this is deliberately broader than {@link isPnpmManagedPackageDir}, which
+ * answers a different question ("is this the copy `pnpm add -g` updates?") and
+ * is checked FIRST by {@link resolveRunningInstall}. By the time this predicate
+ * decides anything, a pnpm *global* store has already been classified.
+ */
+export declare function isPnpmVirtualStorePackageDir(pkgDir: string): boolean;
+/**
+ * Whether the running CLI is a **local** copy — a project dependency or a
+ * `pnpm dlx` cache — rather than a global install this process may replace.
+ *
+ * This is the guard for HQ-CLI update-loop incident 2026-09-02. A stale
+ * `@indigoai-us/hq-cli@5.69.0` sat in an HQ tree's pnpm virtual store, and the
+ * sync runner (npx, which puts `<cwd>/node_modules/.bin` on PATH) kept invoking
+ * it. The gate saw a build below `minVersion`, derived an npm prefix from the
+ * store path, ran
+ *
+ *   npm install -g --prefix <store> @indigoai-us/hq-cli@latest
+ *
+ * which unpacked a pristine copy into `<store>/lib/node_modules` — a directory
+ * pnpm's shim never reads — then reported success. The next invocation resolved
+ * the same 5.69.0 shim and did it all again, ~25 times an hour forever.
+ *
+ * A local copy has no self-update path at all: replacing it is its owning
+ * project's job, and installing globally would leave the copy that is actually
+ * running untouched. So the gate must say so and stop, not install.
+ */
+export declare function isLocalDependencyPackageDir(pkgDir: string, platform?: NodeJS.Platform): boolean;
+export declare function isLocalDependencyInstall(install: RunningInstall, platform?: NodeJS.Platform): boolean;
+/**
+ * Whether an update to `target` would actually move the install forward.
+ *
+ * Loop protection, independent of the layout bug above: an "update" to a
+ * version that is not strictly newer than what is running can never converge,
+ * so however the target was resolved — a stale dist-tag, a bad cache, a
+ * misconfigured hq-pro pin — the gate must refuse it rather than reinstall on
+ * every invocation and announce success each time.
+ *
+ * Unparseable versions return true: this guard exists to stop a provable
+ * no-op, not to become a new way for the gate to refuse to work.
+ */
+export declare function isNewerVersion(target: string, current: string): boolean;
 /**
  * Where the running CLI is installed and who owns it. Resolved in ONE pass so
  * the package-root walk (which reads and parses a `package.json` per directory
@@ -278,7 +331,7 @@ export declare function probeCliVersion(bin: string): string | null;
 export declare function checkUpdateConvergence(targetVersion: string, deps?: {
     resolveBin?: () => string | null;
     probeVersion?: (bin: string) => string | null;
-}): void;
+}): boolean;
 /** Injectable surface for {@link enforceUpdateRequired} (unit tests). */
 interface EnforceUpdateDeps {
     performUpdateString?: (command: string) => UpdateResult;
@@ -286,7 +339,12 @@ interface EnforceUpdateDeps {
     runner?: UpdateRunner;
     cleanStale?: (prefix: string) => string[];
     acquireLock?: () => UpdateLockHandle | null;
-    checkConvergence?: (targetVersion: string) => void;
+    /**
+     * `false` means the probe *disproved* convergence. `void`/`undefined` keeps
+     * the historical "unverified is fine" behaviour, so an injected stub that
+     * returns nothing still exercises the success path.
+     */
+    checkConvergence?: (targetVersion: string) => boolean | void;
 }
 /**
  * Hard enforcement when the server says we're below `minVersion`. Print a
@@ -346,7 +404,11 @@ export declare const __test__: {
     enforceUpdateRequired: typeof enforceUpdateRequired;
     isBunManagedPackageDir: typeof isBunManagedPackageDir;
     pnpmUpdateEnv: typeof pnpmUpdateEnv;
+    isLocalDependencyInstall: typeof isLocalDependencyInstall;
+    isLocalDependencyPackageDir: typeof isLocalDependencyPackageDir;
+    isNewerVersion: typeof isNewerVersion;
     isPnpmManagedPackageDir: typeof isPnpmManagedPackageDir;
+    isPnpmVirtualStorePackageDir: typeof isPnpmVirtualStorePackageDir;
     npmPrefixFromPackageDir: typeof npmPrefixFromPackageDir;
     nudgeUpdateRecommended: typeof nudgeUpdateRecommended;
     performUpdate: typeof performUpdate;

package/dist/utils/version-gate.js

@@ -34,6 +34,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
+import semver from "semver";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
 import { acquireUpdateLock, } from "./update-lock.js";
@@ -140,6 +141,106 @@ export function isBunManagedPackageDir(pkgDir) {
     }
     return false;
 }
+/**
+ * Whether the package dir sits inside a pnpm **virtual store** — the adjacent
+ * `node_modules/.pnpm` segment pair pnpm creates for every install, global or
+ * not:
+ *
+ *   <proj>/node_modules/.pnpm/@indigoai-us+hq-cli@5.69.0/node_modules/@indigoai-us/hq-cli
+ *
+ * A virtual store is a content-addressed cache keyed by the EXACT version in
+ * the directory name. Nothing on PATH ever resolves through
+ * `<store>/lib/node_modules`, and the store dir is not an npm prefix — so the
+ * one thing that must never happen is treating it as one.
+ *
+ * Note this is deliberately broader than {@link isPnpmManagedPackageDir}, which
+ * answers a different question ("is this the copy `pnpm add -g` updates?") and
+ * is checked FIRST by {@link resolveRunningInstall}. By the time this predicate
+ * decides anything, a pnpm *global* store has already been classified.
+ */
+export function isPnpmVirtualStorePackageDir(pkgDir) {
+    const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    const segments = normalized.split("/").filter(Boolean);
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        if (segments[i] === "node_modules" && segments[i + 1] === ".pnpm")
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether the running CLI is a **local** copy — a project dependency or a
+ * `pnpm dlx` cache — rather than a global install this process may replace.
+ *
+ * This is the guard for HQ-CLI update-loop incident 2026-09-02. A stale
+ * `@indigoai-us/hq-cli@5.69.0` sat in an HQ tree's pnpm virtual store, and the
+ * sync runner (npx, which puts `<cwd>/node_modules/.bin` on PATH) kept invoking
+ * it. The gate saw a build below `minVersion`, derived an npm prefix from the
+ * store path, ran
+ *
+ *   npm install -g --prefix <store> @indigoai-us/hq-cli@latest
+ *
+ * which unpacked a pristine copy into `<store>/lib/node_modules` — a directory
+ * pnpm's shim never reads — then reported success. The next invocation resolved
+ * the same 5.69.0 shim and did it all again, ~25 times an hour forever.
+ *
+ * A local copy has no self-update path at all: replacing it is its owning
+ * project's job, and installing globally would leave the copy that is actually
+ * running untouched. So the gate must say so and stop, not install.
+ */
+export function isLocalDependencyPackageDir(pkgDir, platform = process.platform) {
+    // A pnpm virtual store is local by construction on every platform. (A pnpm
+    // *global* store is classified earlier, by isPnpmManagedPackageDir.)
+    if (isPnpmVirtualStorePackageDir(pkgDir))
+        return true;
+    // On every non-Windows platform npm's global root is ALWAYS
+    // `<prefix>/lib/node_modules` — that is what `npm root -g` reports for
+    // /usr/local, Homebrew, nvm and a user-level `--prefix` alike. So a package
+    // under a `node_modules` with no `lib` parent is not a global install: it is
+    // a project dependency (`<proj>/node_modules/@scope/pkg`) or an npx cache
+    // (`~/.npm/_npx/<hash>/node_modules/@scope/pkg`). Both reproduce the same
+    // loop as the pnpm store — `npm install -g --prefix <dir>` writes
+    // `<dir>/lib/node_modules` while the `.bin` shim keeps resolving
+    // `<dir>/node_modules`.
+    //
+    // Windows is the exception and must keep the old behaviour: its global
+    // layout is `<prefix>\node_modules` with no `lib` segment, so the same test
+    // would misread a genuine global install as local.
+    if (platform === "win32")
+        return false;
+    const segments = pkgDir
+        .replace(/\\/g, "/")
+        .replace(/\/+$/, "")
+        .split("/")
+        .filter(Boolean);
+    const nodeModulesIndex = segments.lastIndexOf("node_modules");
+    if (nodeModulesIndex <= 0)
+        return false;
+    return segments[nodeModulesIndex - 1] !== "lib";
+}
+export function isLocalDependencyInstall(install, platform = process.platform) {
+    return (install.manager === "npm" &&
+        install.packageRoot !== null &&
+        isLocalDependencyPackageDir(install.packageRoot, platform));
+}
+/**
+ * Whether an update to `target` would actually move the install forward.
+ *
+ * Loop protection, independent of the layout bug above: an "update" to a
+ * version that is not strictly newer than what is running can never converge,
+ * so however the target was resolved — a stale dist-tag, a bad cache, a
+ * misconfigured hq-pro pin — the gate must refuse it rather than reinstall on
+ * every invocation and announce success each time.
+ *
+ * Unparseable versions return true: this guard exists to stop a provable
+ * no-op, not to become a new way for the gate to refuse to work.
+ */
+export function isNewerVersion(target, current) {
+    const t = semver.valid(target);
+    const c = semver.valid(current);
+    if (!t || !c)
+        return true;
+    return semver.gt(t, c);
+}
 export function resolveRunningInstall() {
     try {
         const packageRoot = findRunningPackageRoot();
@@ -151,6 +252,13 @@ export function resolveRunningInstall() {
         if (isBunManagedPackageDir(packageRoot)) {
             return { manager: "bun", prefix: null, packageRoot };
         }
+        // A local copy — project dependency, pnpm virtual store, or npx cache.
+        // `npmPrefixFromPackageDir` would hand back the project/cache directory and
+        // `npm install -g --prefix <dir>` then writes where nothing loads from —
+        // see isLocalDependencyPackageDir. There is no npm prefix to report here.
+        if (isLocalDependencyPackageDir(packageRoot)) {
+            return { manager: "npm", prefix: null, packageRoot };
+        }
         return {
             manager: "npm",
             prefix: npmPrefixFromPackageDir(packageRoot),
@@ -506,6 +614,14 @@ function manualUpdateCommand(install, decision) {
 function nudgeUpdateRecommended(decision, install = resolveRunningInstall()) {
     const msg = chalk.yellow(`⚠ A new version of hq-cli is available: ${decision.latestVersion} (current: ${decision.currentVersion}).`);
     console.error(msg);
+    // A local copy is not updated by any global command. Printing the server's
+    // npm-shaped one would send the user to install a second copy that this
+    // invocation still would not use — the same wrong advice the pnpm-global
+    // carve-out exists to avoid.
+    if (isLocalDependencyInstall(install)) {
+        console.error(chalk.dim(`  This copy is a local dependency (${install.packageRoot}); update the project that owns it, or invoke the global \`hq\`.`));
+        return;
+    }
     const command = install.manager === "pnpm"
         ? `pnpm ${buildPnpmInstallArgv().join(" ")}`
         : install.manager === "bun"
@@ -584,21 +700,41 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
         const bin = (deps.resolveBin ?? resolveHqOnPath)();
         if (!bin) {
             console.error(chalk.yellow("⚠ Updated, but couldn't resolve `hq` on PATH to verify the new version took effect."));
-            return;
+            // Unverifiable, not disproven — the caller keeps its success report.
+            return true;
         }
         const reported = (deps.probeVersion ?? probeCliVersion)(bin);
         if (!reported) {
             console.error(chalk.yellow(`⚠ Updated, but \`${bin} --version\` did not respond — couldn't verify the new version took effect.`));
-            return;
+            return true; // unverifiable, see above
         }
         if (reported === targetVersion)
-            return; // converged — the normal case
+            return true; // converged — the normal case
         console.error(chalk.yellow(`⚠ hq updated to ${targetVersion} but PATH still resolves ${bin} at version ${reported} — ` +
             `a second install is shadowing the managed one. Remove it (e.g. \`pnpm remove -g ${CLI_NAME}\`) ` +
             "or the updater will loop forever."));
+        // The warning above fires for ANY mismatch — something other than the copy
+        // we just wrote is winning PATH resolution, which is worth saying either
+        // way. But only a STALE result disproves convergence.
+        //
+        // The install runs `@latest`, not `@<targetVersion>`, so it can legitimately
+        // land a version NEWER than the `latestVersion` the gate was handed: the npm
+        // dist-tag moves between the version-check response and the install, or the
+        // service's value was briefly behind. That is a successful upgrade. Failing
+        // it would exit 75 and reinstall on the next invocation — the very loop this
+        // guard exists to stop.
+        const reportedSemver = semver.valid(reported);
+        const targetSemver = semver.valid(targetVersion);
+        if (reportedSemver &&
+            targetSemver &&
+            semver.gte(reportedSemver, targetSemver)) {
+            return true;
+        }
+        return false;
     }
     catch {
         // Verification is best-effort; never break the CLI over a probe.
+        return true;
     }
 }
 /**
@@ -629,6 +765,26 @@ function enforceUpdateRequired(decision, deps = {}) {
     // `resolveRunningInstall`
     // already reports `prefix: null` there and neither is consulted below.
     const install = (deps.resolveInstall ?? resolveRunningInstall)();
+    // Loop protection #1 — nothing here can update a copy this process does not
+    // own. Installing globally would leave the local copy that is actually
+    // running stale, so the gate would fire again on the very next invocation.
+    // Say what to fix and stop; do NOT spend an install.
+    if (isLocalDependencyInstall(install)) {
+        console.error(chalk.red(`  This copy is a local dependency, not a global install: ${install.packageRoot}`));
+        console.error(chalk.dim("  Self-update cannot replace it — an install would land where this copy is never loaded from, and the gate would fire again on the next run."));
+        console.error(chalk.dim(`  Update the project that owns it (e.g. \`pnpm update ${CLI_NAME}\` in its root, or remove the stale dependency), or invoke the global \`hq\` instead.`));
+        process.exit(75);
+    }
+    // Loop protection #2 — an "update" to a version that is not strictly newer
+    // than what is running can never converge. Whatever produced the target (a
+    // stale dist-tag, a bad cache, a misconfigured pin), reinstalling it on every
+    // invocation and announcing success each time is strictly worse than saying
+    // so once.
+    if (!isNewerVersion(decision.latestVersion, decision.currentVersion)) {
+        console.error(chalk.red(`  Refusing to update: the offered version ${decision.latestVersion} is not newer than the installed ${decision.currentVersion}.`));
+        console.error(chalk.dim("  This is a server-side or registry problem, not a local one — reinstalling would loop without ever converging."));
+        process.exit(75);
+    }
     const isManagedOutsideNpm = install.manager !== "npm";
     const prefix = install.prefix;
     if (!isManagedOutsideNpm && !command && !prefix) {
@@ -768,11 +924,17 @@ function attemptRequiredUpdate(decision, deps, install) {
         }
         return 75;
     }
-    console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
     // Read-your-writes: a "successful" install into the npm prefix does not
-    // prove the user's PATH resolves it. Warn (once, no retry) when a ghost
-    // install is shadowing the copy we just wrote — see checkUpdateConvergence.
-    (deps.checkConvergence ?? checkUpdateConvergence)(decision.latestVersion);
+    // prove the user's PATH resolves it. Verify BEFORE announcing, so a ghost
+    // install shadowing the copy we just wrote is reported as the failed update
+    // it is rather than as a success the caller will keep retrying — see
+    // checkUpdateConvergence.
+    const converged = (deps.checkConvergence ?? checkUpdateConvergence)(decision.latestVersion);
+    if (converged === false) {
+        console.error(chalk.red(`✗ Update did not take effect: \`hq\` on PATH still resolves a different build than ${decision.latestVersion}.`));
+        return 75;
+    }
+    console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
     return 0;
 }
 export async function enforceVersionGate(onUpdateRecommended) {
@@ -829,7 +991,11 @@ export const __test__ = {
     enforceUpdateRequired,
     isBunManagedPackageDir,
     pnpmUpdateEnv,
+    isLocalDependencyInstall,
+    isLocalDependencyPackageDir,
+    isNewerVersion,
     isPnpmManagedPackageDir,
+    isPnpmVirtualStorePackageDir,
     npmPrefixFromPackageDir,
     nudgeUpdateRecommended,
     performUpdate,

package/package.json

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