@indigoai-us/hq-cli 5.106.1 → 5.106.3

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [5.106.3] — 2026-09-02
+
+## [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/commands/run.js

@@ -8,6 +8,8 @@ import { computeSha256 } from '../utils/integrity.js';
 import { vaultApiFetch, getCompanyUid } from '../utils/vault-api.js';
 import { discoverSchemas } from '../run/discover-schemas.js';
 import { installHqPlugin, prewarmHqSecrets } from '../run/hq-plugin.js';
+import { assertEnvGraphLoaded, resolveEnvValuesOrThrow, EnvGraphLoadError, EnvResolutionError, } from '../run/env-graph-guard.js';
+import { hadFatalRejection } from '../unhandled-rejection-boundary.js';
 const SECRET_LOAD_TIMEOUT_MS = 30_000;
 export async function buildRunUsage(scriptPath, scriptId) {
     if (scriptId && !scriptPath) {
@@ -119,8 +121,18 @@ export function registerRunCommand(program) {
                 entryFilePaths: paths,
                 afterInit: async (g) => { state = installHqPlugin(g, pluginOpts); },
             });
+            // Refuse to resolve a graph varlock never finished loading (a malformed
+            // .env.schema / .env.local): resolving an unprocessed item whose key is
+            // also in process.env reaches varlock's `expected dataType to be set`
+            // invariant as a FLOATED, never-settling rejection — the CLI then exits
+            // 0 with the command never run (HQ-CLI-W). Run this BEFORE prewarm so a
+            // bad file can never trigger a secret fetch.
+            assertEnvGraphLoaded(graph);
             await prewarmHqSecrets(graph, pluginOpts, state);
-            await graph.resolveEnvValues();
+            // Defence in depth: convert a floated resolution rejection into a thrown
+            // error instead of hanging on varlock's never-settling promise, in case
+            // the shape-dependent guard above ever silently degrades.
+            await resolveEnvValuesOrThrow(graph);
             const schemaErrors = Object.entries(graph.configSchema)
                 .filter(([, item]) => item.errors?.length > 0);
             if (schemaErrors.length > 0) {
@@ -147,10 +159,21 @@ export function registerRunCommand(program) {
                 if (signal) {
                     process.kill(process.pid, signal);
                 }
-                process.exit(code ?? 1);
+                // A fatal floated rejection during the child run set process.exitCode,
+                // which this explicit exit would otherwise erase. Force a non-zero
+                // code so such a rejection is never masked by a child that exited 0,
+                // while still propagating a genuine non-zero child status.
+                process.exit(hadFatalRejection() ? (code || 1) : (code ?? 1));
             });
         }
         catch (err) {
+            // Typed varlock env-schema failures are the user's file, not an hq-cli
+            // defect. Re-throw them so main.ts's handleTopLevelError prints one
+            // actionable `hq:` line and skips Sentry capture; everything else keeps
+            // run.ts's existing `Error:`-prefixed exit-1 behaviour.
+            if (err instanceof EnvGraphLoadError || err instanceof EnvResolutionError) {
+                throw err;
+            }
             process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
             process.exit(1);
         }

package/dist/index.js

@@ -7,10 +7,20 @@ import { CLI_VERSION } from "./cli-version.js";
 // Dependency-light: a pure parser + table, no command graph. Safe to load on
 // every path (including --version) without reintroducing the heavy startup.
 import { isFastCoreRequest } from "./commands/scaffold-fast.js";
+// Also dependency-light: registers a process-level rejection boundary; its only
+// heavy import (main.js) is lazy and reached only when a rejection fires.
+import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.js";
 function isVersionRequest(argv) {
     const args = argv.slice(2);
     return args.length === 1 && (args[0] === "--version" || args[0] === "-V" || args[0] === "-v");
 }
+// Install BEFORE any dispatch so a floated rejection on ANY path (the command
+// graph or the fast-core forwarder) becomes a non-zero exit. @sentry/node's
+// onUnhandledRejection integration defaults to 'warn' — it captures but does
+// NOT rethrow — so without this the event loop drains and Node exits 0 with the
+// command never run (HQ-CLI-W). Sets process.exitCode only, never process.exit,
+// so runCli's finally still finalizes release health and flushes Sentry.
+installProcessRejectionBoundary();
 if (isVersionRequest(process.argv)) {
     process.stdout.write(`${CLI_VERSION}\n`);
 }
@@ -25,7 +35,8 @@ else {
     // before the fast --version split. Some best-effort teardown work uses
     // unref'd handles; top-level-awaiting runCli() makes Node turn an otherwise
     // successful command into exit 13 when that teardown promise remains pending.
-    // Rejections still become unhandled and preserve a genuine non-zero failure.
+    // A floated rejection here no longer exits 0 silently: the boundary installed
+    // above turns it into a non-zero exit (HQ-CLI-W).
     void import("./main.js").then(({ runCli }) => runCli());
 }
 export const __test__ = { isVersionRequest, isFastCoreRequest };

package/dist/main.js

@@ -75,6 +75,7 @@ import { qmdStoreMissingMessage } from "./utils/qmd-store-missing-error.js";
 import { qmdStoreUnopenableMessage } from "./utils/qmd-store-unopenable-error.js";
 import { hqStateWriteErrorMessage } from "./utils/hq-state-write-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
+import { isVarlockEnvError } from "./run/env-graph-guard.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
 import { isAuthError } from "./utils/auth-error.js";
@@ -463,6 +464,17 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         deps.stderr.write(`hq: ${err.message}\n`);
         deps.setExitCode(1);
     }
+    else if (isVarlockEnvError(err)) {
+        // HQ-CLI-W: `hq run` could not load or resolve a .env.schema/.env.local
+        // because the file itself is malformed. The typed carrier
+        // (EnvGraphLoadError / EnvResolutionError) already names the offending
+        // file and the pinned varlock version, so print that one actionable line
+        // and skip Sentry capture — a user's un-parseable env file is their file,
+        // not an hq-cli defect. A genuinely unclassified floated rejection is not
+        // one of these carriers, so it keeps falling through to the capture arm.
+        deps.stderr.write(`hq: ${err.message}\n`);
+        deps.setExitCode(1);
+    }
     else if (isPackageRootResolutionError(err)) {
         deps.stderr.write(`hq: ${err.message}\n`);
         deps.sentry.captureException(err, {

package/dist/run/env-graph-guard.d.ts

@@ -0,0 +1,83 @@
+/** The varlock version hq-cli is pinned to (package.json `dependencies`). */
+export declare const VARLOCK_PINNED_VERSION = "1.0.0";
+/** A schema/plugin source varlock could not finish loading. */
+interface GuardDataSource {
+    readonly isValid: boolean;
+    readonly loadingError?: {
+        readonly message?: string;
+    } | null;
+    readonly schemaErrors?: ReadonlyArray<{
+        readonly message?: string;
+        readonly isWarning?: boolean;
+    }>;
+    readonly resolutionErrors?: ReadonlyArray<{
+        readonly message?: string;
+    }>;
+    readonly label?: string;
+    /** Present on file-based sources (.env.schema / .env.local). */
+    readonly fullPath?: string;
+}
+interface GuardPlugin {
+    readonly loadingError?: {
+        readonly message?: string;
+    } | null;
+    readonly localPath?: string;
+}
+/**
+ * The structural subset of varlock's EnvGraph this module reads. varlock's
+ * concrete EnvGraph is assignable to it, so `hq run` passes its graph with no
+ * cast. Everything the guard reads is optional so a varlock shape change
+ * degrades to "no problems found" rather than a crash — the resolve-time layer
+ * and the varlock-shape smoke test (src/run/varlock-shape.test.ts) are what
+ * make such a degradation fail loudly.
+ */
+export interface LoadedEnvGraph {
+    readonly sortedDataSources?: ReadonlyArray<GuardDataSource>;
+    readonly plugins?: ReadonlyArray<GuardPlugin>;
+    resolveEnvValues(keys?: Array<string>): Promise<void>;
+}
+/**
+ * A schema/entry file could not be loaded, so the env graph never finished
+ * processing. Carries an actionable, file-naming message; classified by
+ * handleTopLevelError as a user-file error (printed, not reported to Sentry).
+ */
+export declare class EnvGraphLoadError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolving the env graph floated a rejection (varlock's un-awaited resolver).
+ * Converted from the process-level unhandled rejection by resolveEnvValuesOrThrow
+ * so the promise `hq run` awaits can never hang. Classified as a user-file error.
+ */
+export declare class EnvResolutionError extends Error {
+    readonly reason: unknown;
+    constructor(reason: unknown);
+}
+/** True for either typed carrier this module raises. */
+export declare function isVarlockEnvError(err: unknown): boolean;
+/**
+ * Throw a typed, actionable EnvGraphLoadError when varlock did not finish
+ * loading the graph — i.e. when it would have bailed out of finishLoad() before
+ * processing items, leaving them unresolvable. Mirrors finishLoad's two
+ * early-return conditions exactly: any data source with `isValid === false`, or
+ * any plugin with a `loadingError`. A fully-valid graph passes silently.
+ */
+export declare function assertEnvGraphLoaded(graph: LoadedEnvGraph): void;
+/**
+ * Await `graph.resolveEnvValues()`, but convert varlock's floated resolution
+ * rejection into a thrown EnvResolutionError instead of hanging on the promise
+ * that never settles.
+ *
+ * varlock@1.0.0's resolveEnvValues dispatches its per-item resolver un-awaited
+ * and with a dead `_reject`, so a throw inside it becomes a process-level
+ * unhandled rejection AND leaves the returned promise permanently pending. We
+ * race the resolve against a scoped `unhandledRejection` listener: whichever
+ * settles first wins. The listener is prepended (so the prior listeners still
+ * run — nothing is swallowed) and removed in `finally` (restoring the exact
+ * prior listener set, including the no-prior-listener case). If resolve settles
+ * normally the listener never fires; a stray unrelated rejection during the
+ * window is still delivered to the pre-existing listeners.
+ */
+export declare function resolveEnvValuesOrThrow(graph: LoadedEnvGraph): Promise<void>;
+export {};
+//# sourceMappingURL=env-graph-guard.d.ts.map

package/dist/run/env-graph-guard.js

@@ -0,0 +1,155 @@
+// src/run/env-graph-guard.ts
+//
+// Guards for `hq run`'s use of varlock's env graph. Two independent layers
+// close the same class of failure that produced Sentry HQ-CLI-W
+// ("expected dataType to be set", varlock ConfigItem.resolve):
+//
+//   1. assertEnvGraphLoaded(graph) — refuse to resolve a graph varlock never
+//      finished loading. When ANY discovered entry file (.env.schema /
+//      .env.local) fails to parse, varlock's EnvGraph.finishLoad() returns
+//      early — BEFORE it processes items — so every ConfigItem is left with
+//      `dataType === undefined` and NO error attached. Resolving such a graph
+//      reaches varlock's internal invariant `expected dataType to be set` for
+//      any item whose key also exists in process.env (varlock treats the whole
+//      process env as overrides), and — because varlock fires that resolution
+//      as an un-awaited, un-caught promise — the throw becomes a process-level
+//      unhandled rejection while the promise `hq run` awaits NEVER settles.
+//      finishLoad's two early-return conditions are: any data source with
+//      `isValid === false`, or any plugin with a `loadingError`. This guard
+//      mirrors exactly those conditions and throws a typed, actionable error
+//      first, so resolution is never reached with an unprocessed graph.
+//
+//   2. resolveEnvValuesOrThrow(graph) — defence in depth for the case the
+//      shape-dependent guard above cannot see (a future varlock could change
+//      the members it reads). It wraps `graph.resolveEnvValues()` in a
+//      narrowly-scoped `unhandledRejection` window: if varlock floats the
+//      resolution rejection, this converts it into a thrown EnvResolutionError
+//      instead of hanging forever on the never-settling promise. The window is
+//      restored to the exact prior listener set afterwards, and every rejection
+//      it observes is still forwarded to the pre-existing listeners, so it never
+//      swallows an unrelated rejection or permanently alters process semantics.
+//
+// Both failures are a user's malformed schema file, not an hq-cli defect, so
+// main.ts's handleTopLevelError classifies these typed carriers as an
+// actionable `hq: …` line WITHOUT a Sentry capture (see isVarlockEnvError).
+import { claimRejection, releaseRejection, } from "../unhandled-rejection-boundary.js";
+/** The varlock version hq-cli is pinned to (package.json `dependencies`). */
+export const VARLOCK_PINNED_VERSION = "1.0.0";
+/**
+ * A schema/entry file could not be loaded, so the env graph never finished
+ * processing. Carries an actionable, file-naming message; classified by
+ * handleTopLevelError as a user-file error (printed, not reported to Sentry).
+ */
+export class EnvGraphLoadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EnvGraphLoadError";
+    }
+}
+/**
+ * Resolving the env graph floated a rejection (varlock's un-awaited resolver).
+ * Converted from the process-level unhandled rejection by resolveEnvValuesOrThrow
+ * so the promise `hq run` awaits can never hang. Classified as a user-file error.
+ */
+export class EnvResolutionError extends Error {
+    reason;
+    constructor(reason) {
+        const underlying = reason instanceof Error ? reason.message : String(reason);
+        super(`could not resolve your env schema (varlock ${VARLOCK_PINNED_VERSION}): ${underlying}. ` +
+            `This usually means a .env.schema or .env.local file could not be parsed — ` +
+            `check them for syntax errors and try again.`);
+        this.name = "EnvResolutionError";
+        this.reason = reason;
+    }
+}
+/** True for either typed carrier this module raises. */
+export function isVarlockEnvError(err) {
+    return err instanceof EnvGraphLoadError || err instanceof EnvResolutionError;
+}
+/** Collect the human-readable reason(s) a source is invalid, mirroring varlock. */
+function describeSourceFailure(source) {
+    const parts = [];
+    const loadingMessage = source.loadingError?.message;
+    if (loadingMessage)
+        parts.push(loadingMessage);
+    for (const err of source.schemaErrors ?? []) {
+        if (!err.isWarning && err.message)
+            parts.push(err.message);
+    }
+    for (const err of source.resolutionErrors ?? []) {
+        if (err.message)
+            parts.push(err.message);
+    }
+    return parts.length > 0 ? parts.join("; ") : "failed to load";
+}
+/**
+ * Throw a typed, actionable EnvGraphLoadError when varlock did not finish
+ * loading the graph — i.e. when it would have bailed out of finishLoad() before
+ * processing items, leaving them unresolvable. Mirrors finishLoad's two
+ * early-return conditions exactly: any data source with `isValid === false`, or
+ * any plugin with a `loadingError`. A fully-valid graph passes silently.
+ */
+export function assertEnvGraphLoaded(graph) {
+    const problems = [];
+    for (const source of graph.sortedDataSources ?? []) {
+        if (source.isValid === false) {
+            const where = source.fullPath ?? source.label ?? "unknown source";
+            problems.push(`${where}: ${describeSourceFailure(source)}`);
+        }
+    }
+    for (const plugin of graph.plugins ?? []) {
+        if (plugin.loadingError) {
+            const where = plugin.localPath ?? "plugin";
+            problems.push(`${where}: ${plugin.loadingError.message ?? String(plugin.loadingError)}`);
+        }
+    }
+    if (problems.length === 0)
+        return;
+    throw new EnvGraphLoadError(`hq run could not load your env schema (varlock ${VARLOCK_PINNED_VERSION}). ` +
+        `Fix the following and re-run:\n` +
+        problems.map((p) => `  - ${p}`).join("\n"));
+}
+/**
+ * Await `graph.resolveEnvValues()`, but convert varlock's floated resolution
+ * rejection into a thrown EnvResolutionError instead of hanging on the promise
+ * that never settles.
+ *
+ * varlock@1.0.0's resolveEnvValues dispatches its per-item resolver un-awaited
+ * and with a dead `_reject`, so a throw inside it becomes a process-level
+ * unhandled rejection AND leaves the returned promise permanently pending. We
+ * race the resolve against a scoped `unhandledRejection` listener: whichever
+ * settles first wins. The listener is prepended (so the prior listeners still
+ * run — nothing is swallowed) and removed in `finally` (restoring the exact
+ * prior listener set, including the no-prior-listener case). If resolve settles
+ * normally the listener never fires; a stray unrelated rejection during the
+ * window is still delivered to the pre-existing listeners.
+ */
+export async function resolveEnvValuesOrThrow(graph) {
+    let claimedReason;
+    let didClaim = false;
+    const onRejection = (reason) => {
+        // Claim this rejection so the process-wide boundary (index.ts) defers to us
+        // and does not ALSO report it — one failure, one diagnostic. The
+        // pre-existing listeners still fire (this is a prependOnceListener), so the
+        // rejection is never swallowed from the process's normal handling.
+        claimedReason = reason;
+        didClaim = true;
+        claimRejection(reason);
+        rejectRace(new EnvResolutionError(reason));
+    };
+    let rejectRace = () => { };
+    const rejection = new Promise((_resolve, reject) => {
+        rejectRace = reject;
+    });
+    process.prependOnceListener("unhandledRejection", onRejection);
+    try {
+        await Promise.race([graph.resolveEnvValues(), rejection]);
+    }
+    finally {
+        // No-op if the once-listener already fired; restores the prior set exactly.
+        process.removeListener("unhandledRejection", onRejection);
+        if (didClaim)
+            releaseRejection(claimedReason);
+    }
+}
+//# sourceMappingURL=env-graph-guard.js.map

package/dist/unhandled-rejection-boundary.d.ts

@@ -0,0 +1,30 @@
+export declare function hadFatalRejection(): boolean;
+export declare function claimRejection(reason: unknown): void;
+export declare function releaseRejection(reason: unknown): void;
+/** Reset the process-level rejection state. Test-only. */
+export declare function __resetRejectionStateForTests(): void;
+export interface RejectionBoundaryDependencies {
+    /** Reads the current process exit code (undefined when still unset). */
+    readonly getExitCode: () => number | undefined;
+    readonly setExitCode: (code: number) => void;
+    /** Best-effort actionable report; may be async and may not finish before exit. */
+    readonly report: (reason: unknown) => void;
+}
+/**
+ * Handle one floated rejection. Synchronously fixes the exit code — a broken
+ * pipe (EPIPE) is a clean close (0), anything else is a failure (1) — WITHOUT
+ * downgrading a non-zero code a command path already set, then kicks off a
+ * best-effort actionable report. Never calls process.exit, so the command's
+ * finally block (release-health session end + bounded Sentry flush) still runs.
+ */
+export declare function handleFatalRejection(reason: unknown, deps: RejectionBoundaryDependencies): void;
+/**
+ * Register the boundary on `process`, once, before index.ts dispatches into the
+ * command graph. Idempotent so repeated imports/installs add a single listener.
+ * The actionable report routes through main.ts's existing handleTopLevelError
+ * with a NO-OP capture: @sentry/node's integration has already captured the
+ * rejection, so this only adds the classified `hq:` line (and its EPIPE / typed
+ * carve-outs) without a second Sentry event.
+ */
+export declare function installProcessRejectionBoundary(): void;
+//# sourceMappingURL=unhandled-rejection-boundary.d.ts.map

package/dist/unhandled-rejection-boundary.js

@@ -0,0 +1,106 @@
+// src/unhandled-rejection-boundary.ts
+//
+// A process-level unhandledRejection boundary for the CLI entrypoint.
+//
+// @sentry/node's onUnhandledRejection integration defaults to mode 'warn': it
+// CAPTURES a floated rejection but does NOT rethrow it. hq-cli installs no
+// rejection handler of its own, so without this boundary ANY floated rejection
+// (the class that produced Sentry HQ-CLI-W) leaves process.exitCode unset, the
+// event loop drains, and Node exits 0 — a silent success in which the command
+// never ran. index.ts's own comment ("Rejections still become unhandled and
+// preserve a genuine non-zero failure") described the pre-Sentry world and is
+// no longer true; this boundary restores it.
+//
+// The logic is factored out of index.ts so it is unit-testable: importing
+// index.ts for a test would trigger the real command dispatch.
+import { isEpipe } from "./utils/epipe.js";
+// Sticky once a non-EPIPE floated rejection has been handled. `process.exitCode`
+// alone is not enough: a command path that later calls `process.exit(0)` — e.g.
+// `hq run`'s child-`close` handler after a child that exited 0 — would erase the
+// failure. Exit paths that propagate their own status consult this to force a
+// non-zero code instead (see src/commands/run.ts).
+let fatalRejectionSeen = false;
+export function hadFatalRejection() {
+    return fatalRejectionSeen;
+}
+// Rejections a scoped handler (e.g. resolveEnvValuesOrThrow) has already claimed
+// and will surface through the normal command path. The process-wide boundary
+// defers to the claimer so one failure yields exactly one diagnostic rather than
+// both a scoped throw AND a boundary report of the same rejection.
+const claimedRejections = new Set();
+export function claimRejection(reason) {
+    claimedRejections.add(reason);
+}
+export function releaseRejection(reason) {
+    claimedRejections.delete(reason);
+}
+/** Reset the process-level rejection state. Test-only. */
+export function __resetRejectionStateForTests() {
+    fatalRejectionSeen = false;
+    claimedRejections.clear();
+}
+/**
+ * Handle one floated rejection. Synchronously fixes the exit code — a broken
+ * pipe (EPIPE) is a clean close (0), anything else is a failure (1) — WITHOUT
+ * downgrading a non-zero code a command path already set, then kicks off a
+ * best-effort actionable report. Never calls process.exit, so the command's
+ * finally block (release-health session end + bounded Sentry flush) still runs.
+ */
+export function handleFatalRejection(reason, deps) {
+    // A scoped handler already owns this exact rejection and will surface it
+    // through the normal command path; do not exit-code or report it twice.
+    if (claimedRejections.has(reason))
+        return;
+    if (isEpipe(reason)) {
+        // A clean downstream close. Only assert 0 when nothing has already failed.
+        if (deps.getExitCode() === undefined)
+            deps.setExitCode(0);
+    }
+    else {
+        // A genuine fatal rejection: mark it sticky, and mark the run failed unless
+        // a command already set a non-zero code (e.g. a child's exit status).
+        fatalRejectionSeen = true;
+        if (!deps.getExitCode())
+            deps.setExitCode(1);
+    }
+    deps.report(reason);
+}
+let installed = false;
+/**
+ * Register the boundary on `process`, once, before index.ts dispatches into the
+ * command graph. Idempotent so repeated imports/installs add a single listener.
+ * The actionable report routes through main.ts's existing handleTopLevelError
+ * with a NO-OP capture: @sentry/node's integration has already captured the
+ * rejection, so this only adds the classified `hq:` line (and its EPIPE / typed
+ * carve-outs) without a second Sentry event.
+ */
+export function installProcessRejectionBoundary() {
+    if (installed)
+        return;
+    installed = true;
+    process.on("unhandledRejection", (reason) => {
+        handleFatalRejection(reason, {
+            getExitCode: () => process.exitCode,
+            setExitCode: (code) => {
+                process.exitCode = code;
+            },
+            report: (r) => {
+                void import("./main.js")
+                    .then(({ handleTopLevelError }) => handleTopLevelError(r, {
+                    sentry: { captureException: () => undefined },
+                    stderr: process.stderr,
+                    // Print-only. handleFatalRejection already set the authoritative,
+                    // downgrade-guarded exit code synchronously; letting the async
+                    // report re-set it would let handleTopLevelError's EPIPE branch
+                    // (setExitCode(0)) reset an earlier failure to success.
+                    setExitCode: () => { },
+                }))
+                    .catch(() => {
+                    // main.js could not be loaded (a rejection on a path that never
+                    // imported it). The synchronous exit code above still stands.
+                });
+            },
+        });
+    });
+}
+//# sourceMappingURL=unhandled-rejection-boundary.js.map

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.3",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.16.3",
+    "@indigoai-us/hq-cloud": "~6.16.6",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",