@indigoai-us/hq-cli 5.345.108 → 5.345.109

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.345.109] — 2026-10-13
+- `hq` commands no longer fail with "The HQ CLI package is being updated" while
+  the desktop app updates the CLI. They wait for the update (up to 4 minutes,
+  `HQ_CLI_UPDATE_WAIT_MS` to tune) and, if the install changed underneath them,
+  re-run once from the new version.
+
 ## [5.345.108] — 2026-10-13
 - On macOS, `hq` reads your sign-in from the Keychain copy kept by the desktop app and uses whichever of the Keychain and `~/.hq/cognito-tokens.json` is newer (hq-cloud 6.18.67). macOS asks once for access; if you deny it, `hq` keeps using the file until you run `hq auth keychain --retry`.
 

package/dist/index.d.ts

@@ -5,13 +5,21 @@ import { isVersionRequest } from "./version-request.js";
 import { isFastCoreRequest } from "./fast-scaffold.js";
 type PackageUseLeaseLoader = () => Promise<void>;
 type PackageUseUpdateProbe = () => Promise<boolean>;
+/** Resolves true once the command was re-run (exit code already set). */
+type PackageUseUpdateReexec = () => Promise<boolean>;
+/**
+ * Wait (bounded) for a live updater to finish, then re-run this command from
+ * the new install via the same bin path. Guarded against loops by an env flag.
+ */
+declare function waitForUpdateThenReexec(argv?: readonly string[], env?: NodeJS.ProcessEnv, waitForUpdate?: () => Promise<boolean>, run?: (command: string, args: string[], childEnv: NodeJS.ProcessEnv) => Promise<number>): Promise<boolean>;
 declare function isNpmPackageEntry(entryUrl: string): boolean;
-declare function dispatchWithPackageUseLease(entryUrl: string, dispatch: () => void, loadLease?: PackageUseLeaseLoader, updateRequestPending?: PackageUseUpdateProbe): void | Promise<void>;
+declare function dispatchWithPackageUseLease(entryUrl: string, dispatch: () => void, loadLease?: PackageUseLeaseLoader, updateRequestPending?: PackageUseUpdateProbe, waitThenReexec?: PackageUseUpdateReexec): void | Promise<void>;
 declare function runCliEntry(entryUrl: string, dispatch: () => void, loadLease?: PackageUseLeaseLoader): void | Promise<void>;
 export declare const __test__: {
     isVersionRequest: typeof isVersionRequest;
     isFastCoreRequest: typeof isFastCoreRequest;
     dispatchWithPackageUseLease: typeof dispatchWithPackageUseLease;
+    waitForUpdateThenReexec: typeof waitForUpdateThenReexec;
     runCliEntry: typeof runCliEntry;
     isNpmPackageEntry: typeof isNpmPackageEntry;
     acquirePackageUseLease: (prefix: string, version: string, stateDirectory?: string) => Promise<import("./utils/package-use-lease.js").PackageUseLease>;

package/dist/index.js

@@ -230,6 +230,36 @@ function dispatchCliEntry() {
         void runMainWithInstallTreeRecovery();
     }
 }
+const REEXEC_ENV = "HQ_CLI_UPDATE_REEXEC";
+/**
+ * Wait (bounded) for a live updater to finish, then re-run this command from
+ * the new install via the same bin path. Guarded against loops by an env flag.
+ */
+async function waitForUpdateThenReexec(argv = process.argv, env = process.env, waitForUpdate = async () => {
+    const { waitForCurrentPackageUseUpdate } = await import("./utils/package-use-lease.js");
+    return waitForCurrentPackageUseUpdate();
+}, run = async (command, args, childEnv) => {
+    const { spawn } = await import("node:child_process");
+    return await new Promise((resolve) => {
+        const child = spawn(command, args, { stdio: "inherit", env: childEnv });
+        child.on("error", () => resolve(1));
+        child.on("exit", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
+    });
+}) {
+    if (env[REEXEC_ENV] === "1" || !argv[1])
+        return false;
+    let finished = false;
+    try {
+        finished = await waitForUpdate();
+    }
+    catch {
+        return false;
+    }
+    if (!finished)
+        return false;
+    process.exitCode = await run(process.execPath, argv.slice(1), { ...env, [REEXEC_ENV]: "1" });
+    return true;
+}
 function isNpmPackageEntry(entryUrl) {
     return /\/node_modules\/@indigoai-us\/hq-cli\/dist\/index\.js$/i.test(entryUrl);
 }
@@ -260,7 +290,7 @@ function dispatchWithPackageUseLease(entryUrl, dispatch, loadLease = async () =>
 }, updateRequestPending = async () => {
     const { currentPackageUseUpdatePending } = await import("./utils/package-use-lease.js");
     return currentPackageUseUpdatePending();
-}) {
+}, waitThenReexec = waitForUpdateThenReexec) {
     if (!isNpmPackageEntry(entryUrl)) {
         dispatch();
         return;
@@ -270,6 +300,12 @@ function dispatchWithPackageUseLease(entryUrl, dispatch, loadLease = async () =>
             throw error;
         try {
             if (await updateRequestPending()) {
+                // The install tree is being replaced under this process, so the lease
+                // module (or a dependency) failed to load. Wait for the updater, then
+                // run the command again from the freshly installed package instead of
+                // failing a running session's command outright.
+                if (await waitThenReexec())
+                    return;
                 const pending = new Error("The HQ CLI package is being updated; retry after the update finishes");
                 pending.name = "PackageUseUpdatePendingError";
                 throw pending;
@@ -311,6 +347,7 @@ export const __test__ = {
     isVersionRequest,
     isFastCoreRequest,
     dispatchWithPackageUseLease,
+    waitForUpdateThenReexec,
     runCliEntry,
     isNpmPackageEntry,
     acquirePackageUseLease: async (prefix, version, stateDirectory) => {

package/dist/utils/package-use-lease.d.ts

@@ -1,4 +1,12 @@
 export declare const PACKAGE_USE_LEASE_HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_LEASE_HANDOFF";
+/**
+ * How long a command waits for a live updater before giving up. A desktop
+ * `npm install -g` after a reboot routinely runs for minutes (seen ~3 min on
+ * 2026-10-13), so a 30s bound made ordinary commands fail mid-session.
+ * Override with HQ_CLI_UPDATE_WAIT_MS (0 disables waiting).
+ */
+export declare const DEFAULT_UPDATE_WAIT_MS = 240000;
+export declare function updateWaitTimeoutMs(env?: NodeJS.ProcessEnv): number;
 export declare const PACKAGE_USE_LEASE_PURPOSES: readonly ["command", "resident-preload", "mcp-serve", "hook", "daemon"];
 export type PackageUseLeasePurpose = (typeof PACKAGE_USE_LEASE_PURPOSES)[number];
 export declare class PackageUseUpdatePendingError extends Error {
@@ -17,7 +25,7 @@ export interface PackageUseLeaseHandoff {
 }
 export declare function npmPrefix(root: string, platform?: NodeJS.Platform): string | null;
 export declare function packageUseLeaseDirectory(prefix: string, stateDirectory?: string): string;
-declare function waitForUpdateRequest(requestPath: string, timeoutMs: number): void;
+declare function waitForUpdateRequest(requestPath: string, timeoutMs: number, notify?: (() => void) | null): void;
 export declare function acquirePackageUseLease(prefix: string, hqVersion: string, stateDirectory?: string, purpose?: PackageUseLeasePurpose): PackageUseLease;
 /**
  * Create a bounded, per-reexec rendezvous in the current lease directory.
@@ -42,6 +50,12 @@ export declare function releasePackageUseLeaseAfterCommandLoad(_argv?: readonly
 export declare function releasePackageUseLeaseAfterResidentPreload(preload: () => Promise<void>, reportFailure: (error: unknown) => void, release?: () => void): Promise<void>;
 /** True only when a valid update request belongs to a live updater process. */
 export declare function packageUseUpdatePending(prefix: string, stateDirectory?: string): boolean;
+/**
+ * Block (bounded) until a live updater's request for this install clears.
+ * Returns true when no update is pending any more, false on timeout or when
+ * this is not a lease-managed install.
+ */
+export declare function waitForCurrentPackageUseUpdate(timeoutMs?: number): boolean;
 /** True while the desktop updater owns the per-prefix update request. */
 export declare function currentPackageUseUpdatePending(): boolean;
 /** True while the desktop updater owns the per-prefix update request. */

package/dist/utils/package-use-lease.js

@@ -9,6 +9,19 @@ const CLI_NAME = "@indigoai-us/hq-cli";
 const UPDATE_REQUEST = "update.pending.json";
 export const PACKAGE_USE_LEASE_HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_LEASE_HANDOFF";
 const HANDOFF_TIMEOUT_MS = 2_000;
+/**
+ * How long a command waits for a live updater before giving up. A desktop
+ * `npm install -g` after a reboot routinely runs for minutes (seen ~3 min on
+ * 2026-10-13), so a 30s bound made ordinary commands fail mid-session.
+ * Override with HQ_CLI_UPDATE_WAIT_MS (0 disables waiting).
+ */
+export const DEFAULT_UPDATE_WAIT_MS = 240_000;
+export function updateWaitTimeoutMs(env = process.env) {
+    const raw = env.HQ_CLI_UPDATE_WAIT_MS?.trim();
+    if (!raw || !/^\d+$/.test(raw))
+        return DEFAULT_UPDATE_WAIT_MS;
+    return Math.min(Number(raw), 30 * 60 * 1000);
+}
 const PACKAGE_USE_LEASE_HEARTBEAT_INTERVAL_MS = 5 * 60 * 1000;
 let packageUseLeaseHeartbeatIntervalMs = PACKAGE_USE_LEASE_HEARTBEAT_INTERVAL_MS;
 export const PACKAGE_USE_LEASE_PURPOSES = [
@@ -139,8 +152,9 @@ export function packageUseLeaseDirectory(prefix, stateDirectory = packageUseStat
 function packageUseUpdateRequestPath(prefix, stateDirectory) {
     return path.join(packageUseLeaseDirectory(prefix, stateDirectory), UPDATE_REQUEST);
 }
-function waitForUpdateRequest(requestPath, timeoutMs) {
+function waitForUpdateRequest(requestPath, timeoutMs, notify = null) {
     const started = Date.now();
+    let notified = false;
     const sleeper = new Int32Array(new SharedArrayBuffer(4));
     while (true) {
         try {
@@ -167,9 +181,16 @@ function waitForUpdateRequest(requestPath, timeoutMs) {
         if (Date.now() - started >= timeoutMs) {
             throw new PackageUseUpdatePendingError("The HQ CLI package is being updated; retry after the update finishes");
         }
+        if (!notified && notify) {
+            notified = true;
+            notify();
+        }
         Atomics.wait(sleeper, 0, 0, 100);
     }
 }
+function notifyWaitingForUpdate() {
+    process.stderr.write("hq-cli: waiting for the HQ CLI update to finish...\n");
+}
 export function acquirePackageUseLease(prefix, hqVersion, stateDirectory, purpose = "command") {
     const directory = packageUseLeaseDirectory(prefix, stateDirectory);
     mkdirSync(directory, { recursive: true, mode: 0o700 });
@@ -219,7 +240,7 @@ export function acquirePackageUseLease(prefix, hqVersion, stateDirectory, purpos
     };
     const releaseOnExit = () => release();
     for (let attempt = 0; attempt < 2; attempt += 1) {
-        waitForUpdateRequest(requestPath, 30_000);
+        waitForUpdateRequest(requestPath, updateWaitTimeoutMs(), notifyWaitingForUpdate);
         try {
             writeFileSync(tempPath, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 });
             renameSync(tempPath, leasePath);
@@ -407,6 +428,28 @@ export function packageUseUpdatePending(prefix, stateDirectory) {
         throw error;
     }
 }
+/**
+ * Block (bounded) until a live updater's request for this install clears.
+ * Returns true when no update is pending any more, false on timeout or when
+ * this is not a lease-managed install.
+ */
+export function waitForCurrentPackageUseUpdate(timeoutMs = updateWaitTimeoutMs()) {
+    const pkg = findCliPackage(path.dirname(fileURLToPath(import.meta.url)));
+    if (!pkg || isPnpmGlobal(pkg.root) || isBunGlobal(pkg.root))
+        return false;
+    const prefix = npmPrefix(pkg.root);
+    if (!prefix)
+        return false;
+    try {
+        waitForUpdateRequest(packageUseUpdateRequestPath(prefix), timeoutMs, notifyWaitingForUpdate);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof PackageUseUpdatePendingError)
+            return false;
+        throw error;
+    }
+}
 /** True while the desktop updater owns the per-prefix update request. */
 export function currentPackageUseUpdatePending() {
     const pkg = findCliPackage(path.dirname(fileURLToPath(import.meta.url)));

package/package.json

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