@indigoai-us/hq-cli 5.103.11 → 5.103.12

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.103.12] — 2026-08-20
+
 ## [5.103.11] — 2026-08-20
 
 ### Reverted

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

@@ -104,15 +104,18 @@ export declare function buildSelfUpdatePlan(install: RunningInstall): {
  */
 export declare function runUpdateQuiet(cmd: string, args: string[], env?: NodeJS.ProcessEnv): UpdateResult;
 /**
- * Serialize self-updates across concurrent `hq` processes. Without this, a
- * machine running several HQ agents can fire many `npm install -g` at the same
- * global prefix at once, and the losers fail with ENOTEMPTY mid-rename — the
- * exact partial-install state `cleanStalePartialInstall` exists to repair.
- * A caller that cannot take the lock simply skips its update: another process
- * is already installing the very version it wanted.
+ * Serialize self-updates across concurrent `hq` processes AND the hq-sync
+ * menubar app. Without this, a machine running several HQ agents can fire many
+ * `npm install -g` at the same global prefix at once, and the losers fail with
+ * ENOTEMPTY mid-rename — the exact partial-install state
+ * `cleanStalePartialInstall` exists to repair. A caller that cannot take the
+ * lock simply skips its update: another process is already installing the very
+ * version it wanted.
  *
- * `mkdir` is the atomic primitive (same approach as version-check's refresh
- * lock); a lock left behind by a killed process goes stale and is reclaimed.
+ * Delegates to the shared advisory lock in `update-lock.ts`
+ * (`$HOME/.hq/locks/cli-update.lock` — a cross-repo contract also honored by
+ * the hq-sync Rust app), so every updater on the machine contends on ONE lock
+ * instead of each tool keeping its own.
  */
 export declare function acquireUpdateLock(now?: number): (() => void) | null;
 /** Injectable surface so the flow is unit-testable without network or spawns. */

package/dist/utils/self-update.js

@@ -57,13 +57,11 @@
  * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
  */
 import { spawnSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
 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 { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.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.
@@ -71,8 +69,6 @@ import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, bu
 export const REEXEC_GUARD_ENV = "HQ_RESCUE_SELF_UPDATED";
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(CLI_NAME)}/latest`;
 const FETCH_TIMEOUT_MS = 3_000;
-/** A held update lock older than this is treated as abandoned (crashed owner). */
-const UPDATE_LOCK_STALE_MS = 10 * 60 * 1000;
 /** Tail of captured package-manager stderr kept for the failure warning. */
 const DETAIL_MAX_CHARS = 400;
 /** npm `latest` for this package, or null on any failure (offline, 5xx, bad body). */
@@ -150,49 +146,23 @@ export function runUpdateQuiet(cmd, args, env) {
         output.dispose();
     }
 }
-function lockDir() {
-    return path.join(os.homedir(), ".hq", "self-update.lock");
-}
 /**
- * Serialize self-updates across concurrent `hq` processes. Without this, a
- * machine running several HQ agents can fire many `npm install -g` at the same
- * global prefix at once, and the losers fail with ENOTEMPTY mid-rename — the
- * exact partial-install state `cleanStalePartialInstall` exists to repair.
- * A caller that cannot take the lock simply skips its update: another process
- * is already installing the very version it wanted.
+ * Serialize self-updates across concurrent `hq` processes AND the hq-sync
+ * menubar app. Without this, a machine running several HQ agents can fire many
+ * `npm install -g` at the same global prefix at once, and the losers fail with
+ * ENOTEMPTY mid-rename — the exact partial-install state
+ * `cleanStalePartialInstall` exists to repair. A caller that cannot take the
+ * lock simply skips its update: another process is already installing the very
+ * version it wanted.
  *
- * `mkdir` is the atomic primitive (same approach as version-check's refresh
- * lock); a lock left behind by a killed process goes stale and is reclaimed.
+ * Delegates to the shared advisory lock in `update-lock.ts`
+ * (`$HOME/.hq/locks/cli-update.lock` — a cross-repo contract also honored by
+ * the hq-sync Rust app), so every updater on the machine contends on ONE lock
+ * instead of each tool keeping its own.
  */
 export function acquireUpdateLock(now = Date.now()) {
-    const dir = lockDir();
-    const release = () => {
-        try {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-        catch {
-            // best-effort lock cleanup
-        }
-    };
-    try {
-        fs.mkdirSync(path.dirname(dir), { recursive: true });
-        fs.mkdirSync(dir);
-        return release;
-    }
-    catch {
-        try {
-            const stat = fs.statSync(dir);
-            if (now - stat.mtimeMs > UPDATE_LOCK_STALE_MS) {
-                fs.rmSync(dir, { recursive: true, force: true });
-                fs.mkdirSync(dir);
-                return release;
-            }
-        }
-        catch {
-            // lock vanished or is unreadable — treat as held and skip
-        }
-        return null;
-    }
+    const handle = acquireSharedUpdateLock({ now, tool: "hq-cli-self-update" });
+    return handle ? handle.release : null;
 }
 /**
  * Re-run `hq <argv…>` from PATH so the freshly-installed version handles the

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

@@ -0,0 +1,84 @@
+/**
+ * Shared advisory cross-process lock serializing every actor that runs
+ * `npm install -g @indigoai-us/hq-cli` (or the pnpm/bun equivalent) against
+ * the same machine.
+ *
+ * Why: production logs showed FOUR independent updaters — this CLI's hard
+ * version-gate, the soft self-updater, and updaters inside the hq-sync menubar
+ * app — each firing `npm install -g` with no coordination. On a machine with a
+ * second "ghost" install (e.g. a pnpm-global shim shadowing the npm one) the
+ * updaters kept "successfully updating" forever, and eventually two concurrent
+ * installs collided mid-rename (npm stages by renaming the package dir aside
+ * to a hidden `.hq-cli-XXXX` dir), gutting the install: no package.json, no
+ * bin/hq. This lock makes losing that race impossible for cooperating actors.
+ *
+ * ── CROSS-REPO CONTRACT ─────────────────────────────────────────────────────
+ * The lock file path and JSON shape below are a contract shared with the
+ * hq-sync Rust menubar app, which honors the SAME file before running its own
+ * CLI updates. Do not change either without a coordinated hq-sync release.
+ *
+ *   Path:    $HOME/.hq/locks/cli-update.lock
+ *   Content: JSON object with exactly these fields:
+ *     {
+ *       "pid":       <number>  — owning process id,
+ *       "startedAt": <string>  — ISO-8601 acquisition timestamp,
+ *       "tool":      <string>  — which actor holds it (e.g. "hq-cli-version-gate"),
+ *       "version":   <string>  — the holder's own version
+ *     }
+ *   Staleness: a holder is stale when `startedAt` is older than 10 minutes OR
+ *   its `pid` is no longer alive (`kill(pid, 0)` → ESRCH). A stale lock may be
+ *   removed and re-acquired; a fresh one means "someone else is installing the
+ *   very version you want — skip".
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ * Mechanics: acquisition is a single atomic `open(…, 'wx')` (O_CREAT|O_EXCL) —
+ * no mkdir dance, no read-then-write window. Unparseable lock content is
+ * treated as stale (a torn write from a crashed holder must not wedge updates
+ * forever). Everything is best-effort: any unexpected filesystem error reads
+ * as "lock held", because the callers' shared philosophy is that updating is
+ * optional and the CLI keeps working either way.
+ */
+/** A held lock older than this is treated as abandoned (crashed owner). */
+export declare const UPDATE_LOCK_STALE_MS: number;
+/** `tool` recorded when this CLI takes the lock. */
+export declare const UPDATE_LOCK_TOOL = "hq-cli-version-gate";
+export interface UpdateLockInfo {
+    pid: number;
+    startedAt: string;
+    tool: string;
+    version: string;
+}
+export interface UpdateLockHandle {
+    /** Absolute path of the held lock file. */
+    path: string;
+    /** Delete the lock file. Idempotent, never throws. */
+    release: () => void;
+}
+/** Injectable knobs so contention/staleness are unit-testable hermetically. */
+export interface UpdateLockOptions {
+    lockPath?: string;
+    now?: number;
+    /** Override liveness probe (defaults to `process.kill(pid, 0)`). */
+    isPidAlive?: (pid: number) => boolean;
+    tool?: string;
+    version?: string;
+}
+export declare function updateLockPath(): string;
+/**
+ * Whether an existing lock's recorded holder is safe to displace: its
+ * `startedAt` is older than {@link UPDATE_LOCK_STALE_MS}, or its pid is dead.
+ * Unreadable / malformed content is stale by definition — only a crashed or
+ * interrupted holder leaves one behind, and treating it as fresh would block
+ * every future update on this machine.
+ */
+export declare function isLockStale(raw: string | null, now: number, isPidAlive: (pid: number) => boolean): boolean;
+/**
+ * Take the machine-wide CLI-update lock, or return `null` when a fresh holder
+ * has it (this process should skip its install). A stale holder is removed and
+ * acquisition retried exactly once — two genuinely-racing processes still
+ * serialize correctly because the retry goes back through O_EXCL.
+ *
+ * Callers MUST release in a `finally` around the install.
+ */
+export declare function acquireUpdateLock(options?: UpdateLockOptions): UpdateLockHandle | null;
+//# sourceMappingURL=update-lock.d.ts.map

package/dist/utils/update-lock.js

@@ -0,0 +1,173 @@
+/**
+ * Shared advisory cross-process lock serializing every actor that runs
+ * `npm install -g @indigoai-us/hq-cli` (or the pnpm/bun equivalent) against
+ * the same machine.
+ *
+ * Why: production logs showed FOUR independent updaters — this CLI's hard
+ * version-gate, the soft self-updater, and updaters inside the hq-sync menubar
+ * app — each firing `npm install -g` with no coordination. On a machine with a
+ * second "ghost" install (e.g. a pnpm-global shim shadowing the npm one) the
+ * updaters kept "successfully updating" forever, and eventually two concurrent
+ * installs collided mid-rename (npm stages by renaming the package dir aside
+ * to a hidden `.hq-cli-XXXX` dir), gutting the install: no package.json, no
+ * bin/hq. This lock makes losing that race impossible for cooperating actors.
+ *
+ * ── CROSS-REPO CONTRACT ─────────────────────────────────────────────────────
+ * The lock file path and JSON shape below are a contract shared with the
+ * hq-sync Rust menubar app, which honors the SAME file before running its own
+ * CLI updates. Do not change either without a coordinated hq-sync release.
+ *
+ *   Path:    $HOME/.hq/locks/cli-update.lock
+ *   Content: JSON object with exactly these fields:
+ *     {
+ *       "pid":       <number>  — owning process id,
+ *       "startedAt": <string>  — ISO-8601 acquisition timestamp,
+ *       "tool":      <string>  — which actor holds it (e.g. "hq-cli-version-gate"),
+ *       "version":   <string>  — the holder's own version
+ *     }
+ *   Staleness: a holder is stale when `startedAt` is older than 10 minutes OR
+ *   its `pid` is no longer alive (`kill(pid, 0)` → ESRCH). A stale lock may be
+ *   removed and re-acquired; a fresh one means "someone else is installing the
+ *   very version you want — skip".
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ * Mechanics: acquisition is a single atomic `open(…, 'wx')` (O_CREAT|O_EXCL) —
+ * no mkdir dance, no read-then-write window. Unparseable lock content is
+ * treated as stale (a torn write from a crashed holder must not wedge updates
+ * forever). Everything is best-effort: any unexpected filesystem error reads
+ * as "lock held", because the callers' shared philosophy is that updating is
+ * optional and the CLI keeps working either way.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { CLI_VERSION } from "../cli-version.js";
+/** A held lock older than this is treated as abandoned (crashed owner). */
+export const UPDATE_LOCK_STALE_MS = 10 * 60 * 1000;
+/** `tool` recorded when this CLI takes the lock. */
+export const UPDATE_LOCK_TOOL = "hq-cli-version-gate";
+export function updateLockPath() {
+    return path.join(os.homedir(), ".hq", "locks", "cli-update.lock");
+}
+function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH — no such process. EPERM means it exists but is not ours; that
+        // still counts as alive (we must not steal a root-owned updater's lock).
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Whether an existing lock's recorded holder is safe to displace: its
+ * `startedAt` is older than {@link UPDATE_LOCK_STALE_MS}, or its pid is dead.
+ * Unreadable / malformed content is stale by definition — only a crashed or
+ * interrupted holder leaves one behind, and treating it as fresh would block
+ * every future update on this machine.
+ */
+export function isLockStale(raw, now, isPidAlive) {
+    if (raw == null)
+        return true;
+    let info;
+    try {
+        info = JSON.parse(raw);
+    }
+    catch {
+        return true;
+    }
+    if (typeof info.pid !== "number" || typeof info.startedAt !== "string") {
+        return true;
+    }
+    const startedAt = Date.parse(info.startedAt);
+    if (Number.isNaN(startedAt))
+        return true;
+    if (now - startedAt > UPDATE_LOCK_STALE_MS)
+        return true;
+    if (!isPidAlive(info.pid))
+        return true;
+    return false;
+}
+function tryCreate(lockPath, body) {
+    let fd;
+    try {
+        // 'wx' — O_CREAT|O_EXCL|O_WRONLY: fails atomically if the file exists.
+        fd = fs.openSync(lockPath, "wx");
+    }
+    catch {
+        return null;
+    }
+    try {
+        fs.writeSync(fd, body);
+    }
+    catch {
+        // A lock we created but could not stamp is still OURS — keep it.
+    }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // already closed
+        }
+    }
+    return {
+        path: lockPath,
+        release: () => {
+            try {
+                fs.rmSync(lockPath, { force: true });
+            }
+            catch {
+                // best-effort lock cleanup
+            }
+        },
+    };
+}
+/**
+ * Take the machine-wide CLI-update lock, or return `null` when a fresh holder
+ * has it (this process should skip its install). A stale holder is removed and
+ * acquisition retried exactly once — two genuinely-racing processes still
+ * serialize correctly because the retry goes back through O_EXCL.
+ *
+ * Callers MUST release in a `finally` around the install.
+ */
+export function acquireUpdateLock(options = {}) {
+    const lockPath = options.lockPath ?? updateLockPath();
+    const now = options.now ?? Date.now();
+    const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
+    const info = {
+        pid: process.pid,
+        startedAt: new Date(now).toISOString(),
+        tool: options.tool ?? UPDATE_LOCK_TOOL,
+        version: options.version ?? CLI_VERSION,
+    };
+    const body = JSON.stringify(info);
+    try {
+        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    }
+    catch {
+        return null; // can't even create ~/.hq/locks — treat as held, skip update
+    }
+    const first = tryCreate(lockPath, body);
+    if (first)
+        return first;
+    // Lock exists. Fresh holder → back off. Stale → remove and retry ONCE.
+    let raw;
+    try {
+        raw = fs.readFileSync(lockPath, "utf-8");
+    }
+    catch {
+        raw = null; // vanished (holder just released) or unreadable — stale path
+    }
+    if (!isLockStale(raw, now, isPidAlive))
+        return null;
+    try {
+        fs.rmSync(lockPath, { force: true });
+    }
+    catch {
+        return null;
+    }
+    return tryCreate(lockPath, body);
+}
+//# sourceMappingURL=update-lock.js.map

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

@@ -28,6 +28,7 @@
  * to silence both check + gate).
  */
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
+import { type UpdateLockHandle } from "./update-lock.js";
 /** Which package manager owns the running global install. */
 export type InstallManager = "npm" | "pnpm" | "bun";
 export interface VersionCheckResponse {
@@ -250,21 +251,60 @@ declare function performUpdate(command: string, runner?: UpdateRunner): UpdateRe
  */
 declare function nudgeUpdateRecommended(decision: VersionCheckResponse, install?: RunningInstall): void;
 /**
- * Hard enforcement when the server says we're below `minVersion`. Print a
- * red banner, attempt the update, then exit so the user reruns against the
- * fresh binary. Sequence chosen so a user with a broken `npm` global prefix
- * still gets a clear error rather than an opaque silent failure.
+ * The `hq` binary an ordinary shell PATH lookup would run, or null when it
+ * can't be resolved. Uses `command -v` through `/bin/sh` (POSIX) / `where`
+ * (Windows) rather than trusting our own install path — the whole point is to
+ * see what the USER's next invocation resolves.
+ */
+export declare function resolveHqOnPath(): string | null;
+/** `<bin> --version` output (trimmed), or null on any failure/timeout. */
+export declare function probeCliVersion(bin: string): string | null;
+/**
+ * Read-your-writes convergence check, run after an install reports success.
  *
- * Exit codes:
- *   0 — update succeeded; user must rerun their command
- *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
+ * A "successful" `npm install -g` proves only that the npm prefix was
+ * rewritten — NOT that the `hq` the user's PATH resolves is the copy that was
+ * just installed. On a machine with a second "ghost" install (e.g. a
+ * pnpm-global shim at `~/Library/pnpm/bin/hq` shadowing the npm bin dir),
+ * every updater on the box probes the ghost's version, sees it stale, installs
+ * into the npm prefix, reports success, and repeats forever — the production
+ * updater-war this fix exists for. Detect the divergence here, warn ONCE with
+ * the exact shadowing path, and never retry: no number of retries into the
+ * same prefix can change what PATH resolves.
+ *
+ * Advisory only — resolution failure warns once and continues; nothing in
+ * here may crash or block the CLI.
  */
-declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: {
+export declare function checkUpdateConvergence(targetVersion: string, deps?: {
+    resolveBin?: () => string | null;
+    probeVersion?: (bin: string) => string | null;
+}): void;
+/** Injectable surface for {@link enforceUpdateRequired} (unit tests). */
+interface EnforceUpdateDeps {
     performUpdateString?: (command: string) => UpdateResult;
     resolveInstall?: () => RunningInstall;
     runner?: UpdateRunner;
     cleanStale?: (prefix: string) => string[];
-}): never;
+    acquireLock?: () => UpdateLockHandle | null;
+    checkConvergence?: (targetVersion: string) => void;
+}
+/**
+ * Hard enforcement when the server says we're below `minVersion`. Print a
+ * red banner, take the machine-wide update lock, attempt the update, then
+ * exit so the user reruns against the fresh binary. Sequence chosen so a user
+ * with a broken `npm` global prefix still gets a clear error rather than an
+ * opaque silent failure.
+ *
+ * When another updater already holds the lock (fresh, live holder) the gate
+ * SKIPS the install and RETURNS, letting the CLI continue on the current
+ * version — the gate must never break the CLI, and the lock holder is
+ * installing the very version we want anyway.
+ *
+ * Exit codes:
+ *   0 — update succeeded; user must rerun their command
+ *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
+ */
+declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: EnforceUpdateDeps): void;
 /**
  * Public entry point. Call before commander parses argv. Blocks the CLI on
  * network IO for up to FETCH_TIMEOUT_MS — acceptable because the alternative
@@ -291,8 +331,12 @@ export declare function enforceVersionGate(onUpdateRecommended?: (decision: Vers
 export declare function shouldSkipGate(argv: readonly string[]): boolean;
 export declare const __test__: {
     CLIENT_ID: string;
+    CONVERGENCE_TIMEOUT_MS: number;
     ENDPOINT_PATH: string;
     FETCH_TIMEOUT_MS: number;
+    checkUpdateConvergence: typeof checkUpdateConvergence;
+    probeCliVersion: typeof probeCliVersion;
+    resolveHqOnPath: typeof resolveHqOnPath;
     buildBunInstallArgv: typeof buildBunInstallArgv;
     buildPnpmInstallArgv: typeof buildPnpmInstallArgv;
     buildPrefixedInstallArgv: typeof buildPrefixedInstallArgv;

package/dist/utils/version-gate.js

@@ -36,6 +36,7 @@ import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
+import { acquireUpdateLock, } from "./update-lock.js";
 const CLIENT_ID = "hq-cli";
 const ENDPOINT_PATH = "/v1/client-version/check";
 const FETCH_TIMEOUT_MS = 3_000;
@@ -514,11 +515,103 @@ function nudgeUpdateRecommended(decision, install = resolveRunningInstall()) {
         console.error(chalk.dim(`  Update: ${command}`));
     }
 }
+/** Timeout for the read-your-writes PATH/version probes below. A broken or
+ * hung shell must not stall the gate — the probes are advisory only. */
+const CONVERGENCE_TIMEOUT_MS = 3_000;
+/**
+ * The `hq` binary an ordinary shell PATH lookup would run, or null when it
+ * can't be resolved. Uses `command -v` through `/bin/sh` (POSIX) / `where`
+ * (Windows) rather than trusting our own install path — the whole point is to
+ * see what the USER's next invocation resolves.
+ */
+export function resolveHqOnPath() {
+    try {
+        const probe = process.platform === "win32"
+            ? spawnSync("where", ["hq"], {
+                encoding: "utf-8",
+                timeout: CONVERGENCE_TIMEOUT_MS,
+            })
+            : spawnSync("/bin/sh", ["-c", "command -v hq"], {
+                encoding: "utf-8",
+                timeout: CONVERGENCE_TIMEOUT_MS,
+            });
+        if (probe.error || probe.status !== 0)
+            return null;
+        const first = (probe.stdout ?? "")
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)[0];
+        return first ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `<bin> --version` output (trimmed), or null on any failure/timeout. */
+export function probeCliVersion(bin) {
+    try {
+        const result = spawnSync(bin, ["--version"], {
+            encoding: "utf-8",
+            timeout: CONVERGENCE_TIMEOUT_MS,
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        const out = (result.stdout ?? "").trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read-your-writes convergence check, run after an install reports success.
+ *
+ * A "successful" `npm install -g` proves only that the npm prefix was
+ * rewritten — NOT that the `hq` the user's PATH resolves is the copy that was
+ * just installed. On a machine with a second "ghost" install (e.g. a
+ * pnpm-global shim at `~/Library/pnpm/bin/hq` shadowing the npm bin dir),
+ * every updater on the box probes the ghost's version, sees it stale, installs
+ * into the npm prefix, reports success, and repeats forever — the production
+ * updater-war this fix exists for. Detect the divergence here, warn ONCE with
+ * the exact shadowing path, and never retry: no number of retries into the
+ * same prefix can change what PATH resolves.
+ *
+ * Advisory only — resolution failure warns once and continues; nothing in
+ * here may crash or block the CLI.
+ */
+export function checkUpdateConvergence(targetVersion, deps = {}) {
+    try {
+        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;
+        }
+        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;
+        }
+        if (reported === targetVersion)
+            return; // 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."));
+    }
+    catch {
+        // Verification is best-effort; never break the CLI over a probe.
+    }
+}
 /**
  * Hard enforcement when the server says we're below `minVersion`. Print a
- * red banner, attempt the update, then exit so the user reruns against the
- * fresh binary. Sequence chosen so a user with a broken `npm` global prefix
- * still gets a clear error rather than an opaque silent failure.
+ * red banner, take the machine-wide update lock, attempt the update, then
+ * exit so the user reruns against the fresh binary. Sequence chosen so a user
+ * with a broken `npm` global prefix still gets a clear error rather than an
+ * opaque silent failure.
+ *
+ * When another updater already holds the lock (fresh, live holder) the gate
+ * SKIPS the install and RETURNS, letting the CLI continue on the current
+ * version — the gate must never break the CLI, and the lock holder is
+ * installing the very version we want anyway.
  *
  * Exit codes:
  *   0 — update succeeded; user must rerun their command
@@ -545,6 +638,38 @@ function enforceUpdateRequired(decision, deps = {}) {
         }
         process.exit(75);
     }
+    // Serialize against every other updater on the machine (other hq processes,
+    // the hq-sync menubar app) via the shared advisory lock — see update-lock.ts
+    // for the cross-repo contract. A fresh holder means someone else is already
+    // installing the version we want: skip and continue on the current version
+    // (the gate must never break the CLI).
+    const lock = (deps.acquireLock ?? acquireUpdateLock)();
+    if (!lock) {
+        console.error(chalk.dim("  Another hq updater is already installing (update lock held); continuing on the current version."));
+        return;
+    }
+    let exitCode;
+    try {
+        exitCode = attemptRequiredUpdate(decision, deps, install);
+    }
+    finally {
+        // `process.exit` skips `finally` blocks, so the exit itself lives OUTSIDE
+        // the lock scope; this `finally` releases on the normal path and on any
+        // unexpected throw from the install attempt.
+        lock.release();
+    }
+    process.exit(exitCode);
+}
+/**
+ * The install attempt itself (npm/pnpm/bun routing, stale-partial cleanup,
+ * sudo fallback, post-success convergence check). Runs with the machine-wide
+ * update lock held. Returns the process exit code: 0 on success, 75
+ * (EX_TEMPFAIL) on failure.
+ */
+function attemptRequiredUpdate(decision, deps, install) {
+    const command = decision.updateCommand;
+    const isManagedOutsideNpm = install.manager !== "npm";
+    const prefix = install.prefix;
     const runner = deps.runner ?? runUpdateCommand;
     // Resolve the concrete install argv once so the sudo fallback below can re-run
     // the EXACT same command under elevation.
@@ -641,10 +766,14 @@ function enforceUpdateRequired(decision, deps = {}) {
         if (isManagedOutsideNpm && result.code === "ENOENT" && command) {
             console.error(chalk.dim(`  (hq-pro suggests \`${command}\` — that is for npm-managed installs; use it only if you have switched this install to npm.)`));
         }
-        process.exit(75);
+        return 75;
     }
     console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
-    process.exit(0);
+    // 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);
+    return 0;
 }
 export async function enforceVersionGate(onUpdateRecommended) {
     if (isOptedOut())
@@ -658,7 +787,10 @@ export async function enforceVersionGate(onUpdateRecommended) {
     // neither downstream path repeats it.
     const install = resolveRunningInstall();
     if (decision.updateRequired) {
-        enforceUpdateRequired(decision, { resolveInstall: () => install }); // exits process
+        // Exits the process, EXCEPT when another updater holds the shared update
+        // lock — then it returns and the CLI continues on the current version.
+        enforceUpdateRequired(decision, { resolveInstall: () => install });
+        return "continue";
     }
     if (decision.updateRecommended) {
         if (onUpdateRecommended) {
@@ -682,8 +814,12 @@ export function shouldSkipGate(argv) {
 }
 export const __test__ = {
     CLIENT_ID,
+    CONVERGENCE_TIMEOUT_MS,
     ENDPOINT_PATH,
     FETCH_TIMEOUT_MS,
+    checkUpdateConvergence,
+    probeCliVersion,
+    resolveHqOnPath,
     buildBunInstallArgv,
     buildPnpmInstallArgv,
     buildPrefixedInstallArgv,

package/package.json

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