@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/utils/version-gate.js

@@ -28,25 +28,33 @@
  * to silence both check + gate).
  */
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
-import { accessSync, closeSync, constants as fsConstants, existsSync, mkdtempSync, openSync, readdirSync, readFileSync, rmSync, } from "node:fs";
+import { accessSync, closeSync, constants as fsConstants, copyFileSync, existsSync, mkdirSync, mkdtempSync, openSync, readdirSync, realpathSync, readFileSync, rmSync, } from "node:fs";
 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 { Sentry } from "../sentry.js";
+import { isCliTelemetryDisabled } from "./cli-telemetry.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;
 const LATEST_PACKAGE_SPEC = `${CLI_NAME}@latest`;
+let currentVersionGatePhase = "unknown";
+/** The last closed version-gate phase observed in this process. */
+export function getVersionGatePhase() {
+    return currentVersionGatePhase;
+}
 function isOptedOut() {
     return process.env.HQ_NO_UPDATE_CHECK === "1";
 }
-function findRunningPackageRoot() {
-    let dir = path.dirname(fileURLToPath(import.meta.url));
+function findCliPackageRoot(startDir) {
+    let dir = startDir;
     while (true) {
         try {
             const pkg = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf-8"));
@@ -62,6 +70,105 @@ function findRunningPackageRoot() {
         dir = parent;
     }
 }
+function findRunningPackageRoot() {
+    return findCliPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
+}
+/** Resolve an on-PATH executable back to the installed hq-cli package it loads. */
+function findPackageRootForExecutable(bin) {
+    try {
+        const packageRoot = findCliPackageRoot(path.dirname(realpathSync(bin)));
+        if (packageRoot)
+            return packageRoot;
+    }
+    catch {
+        // A missing or inaccessible executable may still be recoverable from the
+        // configured pnpm global layout below.
+    }
+    // pnpm emits shell/.cmd shims into its global bin directory. realpathSync()
+    // resolves symlinks, but a generated shim is a regular file, so walking up
+    // from its real path never reaches the package it invokes. Look up only the
+    // hq-cli package under the matching PNPM_HOME/global layout instead.
+    const binDir = path.dirname(bin);
+    const configuredHome = process.env.PNPM_HOME;
+    const inferredHome = path.basename(binDir).toLowerCase() === "bin"
+        ? path.dirname(binDir)
+        : binDir;
+    const candidateHomes = [configuredHome, inferredHome].filter((home, index, homes) => Boolean(home) && homes.findIndex((candidate) => candidate === home) === index);
+    const home = candidateHomes.find((candidate) => samePath(binDir, candidate) ||
+        samePath(binDir, path.join(candidate, "bin")));
+    if (!home)
+        return null;
+    const globalRoot = path.join(home, "global");
+    let storeVersions;
+    try {
+        storeVersions = readdirSync(globalRoot);
+    }
+    catch {
+        return null;
+    }
+    const packageSegments = CLI_NAME.split("/");
+    for (const storeVersion of storeVersions) {
+        const storeRoot = path.join(globalRoot, storeVersion);
+        const packageRoots = [
+            path.join(storeRoot, "node_modules", ...packageSegments),
+        ];
+        // pnpm v11 adds a hash between its global store version and node_modules.
+        // Its documented `vN` global layout is recognized unconditionally below.
+        if (/^v\d+$/.test(storeVersion)) {
+            try {
+                for (const hash of readdirSync(storeRoot)) {
+                    packageRoots.push(path.join(storeRoot, hash, "node_modules", ...packageSegments));
+                }
+            }
+            catch {
+                // A missing or unreadable version directory is simply not a candidate.
+            }
+        }
+        for (const candidate of packageRoots) {
+            const packageRoot = findCliPackageRoot(candidate);
+            if (packageRoot &&
+                samePath(packageRoot, candidate) &&
+                isPnpmManagedPackageDir(packageRoot, true)) {
+                return packageRoot;
+            }
+        }
+    }
+    return null;
+}
+function samePath(left, right) {
+    const canonical = (value) => {
+        try {
+            return realpathSync(value);
+        }
+        catch {
+            return path.resolve(value);
+        }
+    };
+    const a = canonical(left);
+    const b = canonical(right);
+    return process.platform === "win32"
+        ? a.toLowerCase() === b.toLowerCase()
+        : a === b;
+}
+function globalInstallManagerForPath(bin, packageRoot) {
+    if (isPnpmManagedPackageDir(packageRoot, true)) {
+        return "pnpm";
+    }
+    if (isBunManagedPackageDir(packageRoot))
+        return "bun";
+    const prefix = npmPrefixFromPackageDir(packageRoot);
+    if (!prefix)
+        return null;
+    const normalizedRoot = packageRoot.replace(/\\/g, "/");
+    const normalizedPrefix = prefix.replace(/\\/g, "/").replace(/\/$/, "");
+    // POSIX global npm packages live under <prefix>/lib/node_modules. On
+    // Windows npm puts hq.cmd directly in <prefix>, so also verify the bin's
+    // directory against the prefix-derived shim location there.
+    const posixGlobal = normalizedRoot.includes("/lib/node_modules/");
+    const windowsGlobal = process.platform === "win32" &&
+        samePath(path.dirname(bin), normalizedPrefix);
+    return posixGlobal || windowsGlobal ? "npm" : null;
+}
 export function npmPrefixFromPackageDir(pkgDir) {
     const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
     const segments = normalized.split("/");
@@ -93,8 +200,8 @@ function pnpmHomeGlobalRoot() {
  * on PATH:
  *
  *   $PNPM_HOME/hq                                        <- shim on PATH
- *   $PNPM_HOME/global/5/node_modules/@indigoai-us/hq-cli <- symlink
- *   $PNPM_HOME/global/5/.pnpm/@indigoai-us+hq-cli@5.61.0/node_modules/…
+ *   pnpm through v10: $PNPM_HOME/global/5/node_modules/@indigoai-us/hq-cli
+ *   pnpm v11+:       $PNPM_HOME/global/v11/<hash>/node_modules/@indigoai-us/hq-cli
  *
  * Both the symlinked and the resolved (`.pnpm`) form are recognised, because
  * whether `import.meta.url` reports the link or its target depends on how node
@@ -108,18 +215,26 @@ function pnpmHomeGlobalRoot() {
  * i.e. the gate would re-fire and re-install globally on every subsequent run.
  * Those layouts fall through to the ordinary npm-prefix/manual handling.
  */
-export function isPnpmManagedPackageDir(pkgDir) {
+export function isPnpmManagedPackageDir(pkgDir, acceptVersionPrefixedGlobalDir = true) {
     const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
     const segments = normalized.split("/").filter(Boolean);
-    // `global/<digits>` — pnpm's global root, in either the symlinked or the
-    // resolved (`.pnpm`) form, and independent of where PNPM_HOME points.
+    // pnpm through v10 uses `global/<digits>`; pnpm v11+ uses
+    // `global/v<major>`. Recognize both documented layouts, and require a
+    // version segment so `global/next` or a `v11` directory elsewhere cannot be
+    // mistaken for a global install.
     for (let i = 0; i < segments.length - 1; i += 1) {
-        if (segments[i] === "global" && /^\d+$/.test(segments[i + 1]))
+        if (segments[i] !== "global")
+            continue;
+        const globalDirVersion = segments[i + 1];
+        if (/^\d+$/.test(globalDirVersion))
             return true;
+        if (acceptVersionPrefixedGlobalDir && /^v\d+$/.test(globalDirVersion)) {
+            return true;
+        }
     }
-    // Belt-and-braces for a future pnpm layout whose store dir is not numeric:
-    // anything under `$PNPM_HOME/global` is global by construction. Still keyed
-    // on the `global` segment so `$PNPM_HOME/store/**` (dlx caches) stays out.
+    // PNPM_HOME/global is pnpm's configured global root by construction, so
+    // keep this fallback in both flag states. The flag above gates only the new
+    // documented global/v<major> segment match outside that configured root.
     const globalRoot = pnpmHomeGlobalRoot();
     if (globalRoot) {
         if (normalized === globalRoot || normalized.startsWith(`${globalRoot}/`)) {
@@ -246,7 +361,7 @@ export function resolveRunningInstall() {
         const packageRoot = findRunningPackageRoot();
         if (!packageRoot)
             return { manager: "npm", prefix: null, packageRoot: null };
-        if (isPnpmManagedPackageDir(packageRoot)) {
+        if (isPnpmManagedPackageDir(packageRoot, true)) {
             return { manager: "pnpm", prefix: null, packageRoot };
         }
         if (isBunManagedPackageDir(packageRoot)) {
@@ -278,9 +393,9 @@ export function resolveRunningPrefix() {
     return resolveRunningInstall().prefix;
 }
 /**
- * Whether the current process can write the npm global `prefix` — i.e. whether
- * an `npm install -g --prefix <prefix>` could actually replace the installed
- * CLI, or would fail with EACCES.
+ * Whether the current process can write the npm global install targets — i.e.
+ * whether an `npm install -g --prefix <prefix>` could actually replace the
+ * installed CLI, or would fail with EACCES.
  *
  * The path npm rewrites is the prefix's `bin` dir (`<prefix>/bin/hq` on unix
  * globals — the `rename /usr/bin/hq` EACCES the agent boxes hit), so that is
@@ -309,17 +424,119 @@ export function isPrefixWritable(prefix, access = (target, mode) => accessSync(t
     return false;
 }
 /**
- * One-line operator explanation for a failed global update whose prefix the
- * running user cannot write. This is the agent-box case: the CLI is a
- * root-owned `/usr` global install and the runtime is unprivileged, so the
- * update genuinely cannot converge from here and re-trying it silently would
- * loop. Says so plainly and points at the paths that CAN update it.
+ * Check the directories an npm global update must mutate before spawning npm.
+ * Npm replaces the package under node_modules and writes executable links
+ * under prefix/bin. The package's parent must be writable because npm renames
+ * the old package there.
+ *
+ * When one of those directories has not been created yet, check its nearest
+ * existing ancestor: npm can create a child only if that ancestor is writable.
  */
-export function nonWritablePrefixNote(prefix) {
-    return (`The npm global prefix ${prefix} is not writable by the current user, so this update cannot ` +
-        `take effect here. On an agent box this is expected: the CLI is a root-owned global install and ` +
-        `updates land as root — via the box's hq-cli-update timer, or \`sudo npm install -g ${CLI_NAME}@latest\` — ` +
-        `not from the unprivileged runtime.`);
+export function canWriteNpmInstall(prefix, packageRoot, access = (target, mode) => accessSync(target, mode)) {
+    let nodeModulesRoot = path.join(prefix, process.platform === "win32" ? "node_modules" : "lib/node_modules");
+    let cursor = path.resolve(packageRoot);
+    while (true) {
+        if (path.basename(cursor).toLowerCase() === "node_modules") {
+            nodeModulesRoot = cursor;
+            break;
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    const mode = fsConstants.W_OK | fsConstants.X_OK;
+    // npm needs write access to the directories it replaces or links into. The
+    // prefix root itself need not be writable when those directories already
+    // exist; when one is missing, the nearest-existing-ancestor check below
+    // still verifies permission to create it.
+    const targets = [path.join(prefix, "bin"), nodeModulesRoot, path.dirname(packageRoot)];
+    return targets.every((target) => {
+        let candidate = path.resolve(target);
+        while (true) {
+            try {
+                access(candidate, mode);
+                return true;
+            }
+            catch (error) {
+                if (error?.code !== "ENOENT") {
+                    return false;
+                }
+                const parent = path.dirname(candidate);
+                if (parent === candidate)
+                    return false;
+                candidate = parent;
+            }
+        }
+    });
+}
+const nonWritablePrefixNotices = new Set();
+/** Claim the one local warning/report for this installed version and prefix. */
+export function claimNonWritableNpmPrefixNotice(install, fromVersion, homeDir = os.homedir(), kind = "user") {
+    const installIdentity = path.resolve(install.packageRoot ?? install.prefix ?? `${install.manager}:unknown-install`);
+    const identity = createHash("sha256")
+        .update(`${installIdentity}\0${fromVersion}`)
+        .digest("hex");
+    const localKey = path.join(homeDir, ".hq", "self-update", "prefix-not-writable", `${kind}-${identity}`);
+    if (nonWritablePrefixNotices.has(localKey))
+        return false;
+    try {
+        mkdirSync(path.dirname(localKey), { recursive: true, mode: 0o700 });
+        const descriptor = openSync(localKey, "wx", 0o600);
+        closeSync(descriptor);
+        nonWritablePrefixNotices.add(localKey);
+        return true;
+    }
+    catch (error) {
+        if (error?.code === "EEXIST") {
+            nonWritablePrefixNotices.add(localKey);
+            return false;
+        }
+        // Preserve the warning/report for this process if the home directory is
+        // unavailable. The marker is normally durable across CLI invocations.
+        console.error(chalk.dim("hq: could not persist the self-update permission notice rate limit."));
+        nonWritablePrefixNotices.add(localKey);
+        return true;
+    }
+}
+/** Emit one path-free warning event for a handled non-writable npm prefix. */
+export function captureNonWritableNpmPrefixNotice(input) {
+    if (isCliTelemetryDisabled(input.env ?? process.env))
+        return Promise.resolve();
+    const claimed = claimNonWritableNpmPrefixNotice(input.install, input.fromVersion, input.homeDir, "report");
+    if (!claimed)
+        return Promise.resolve();
+    Sentry.captureMessage("Self-update deferred: npm prefix is not writable", {
+        level: "warning",
+        fingerprint: ["self-update", "npm-prefix-not-writable"],
+        tags: {
+            from_version: input.fromVersion,
+            target_version: input.targetVersion,
+            install_flavor: "npm",
+            error_class: "prefix_not_writable",
+            error_reason: "permission_denied",
+        },
+    });
+    return Sentry.flush(2_000).then((flushed) => {
+        if (!flushed) {
+            console.error(chalk.dim("hq: the self-update permission notice could not be sent to Sentry yet."));
+        }
+    });
+}
+/** One-line repair guidance for a global npm install the current user cannot write. */
+export function nonWritablePrefixNote(prefix, platform = process.platform) {
+    const prefixArg = `'${prefix.replace(/'/g, "'\\''")}'`;
+    if (platform === "win32") {
+        const windowsPrefixArg = `"${prefix.replace(/"/g, '""')}"`;
+        return (`The npm global prefix ${prefix} is not writable by the current user, so hq-cli was not updated. ` +
+            `Open PowerShell as Administrator and run \`npm install -g --prefix ${windowsPrefixArg} ${CLI_NAME}@latest\`, ` +
+            `or set a user-owned prefix with \`npm config set prefix "$env:APPDATA\\npm"\` and run ` +
+            `\`npm install -g ${CLI_NAME}@latest\` from that PowerShell session.`);
+    }
+    return (`The npm global prefix ${prefix} is not writable by the current user, so hq-cli was not updated. ` +
+        `Run \`sudo npm install -g --prefix ${prefixArg} ${CLI_NAME}@latest\` to update this install, ` +
+        `or switch to a user-owned prefix with \`npm config set prefix ~/.npm-global\`, then run ` +
+        `\`npm install -g ${CLI_NAME}@latest\` after adding ~/.npm-global/bin to PATH.`);
 }
 /**
  * Derive `PNPM_HOME` from a pnpm-managed install's own path. pnpm resolves its
@@ -470,7 +687,7 @@ export function cleanStalePartialInstall(prefix, fs = nodeStaleInstallFs) {
  * `null` on any failure (caller treats as "no gate"). Tight 3s timeout —
  * a hung server must not delay CLI startup.
  */
-async function fetchVersionDecision() {
+async function fetchVersionDecision(timeoutMs = FETCH_TIMEOUT_MS) {
     try {
         const url = `${DEFAULT_VAULT_API_URL}${ENDPOINT_PATH}`;
         const res = await fetch(url, {
@@ -484,7 +701,7 @@ async function fetchVersionDecision() {
                 currentVersion: CLI_VERSION,
                 platform: `${process.platform}-${process.arch}`,
             }),
-            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            signal: AbortSignal.timeout(timeoutMs),
         });
         if (!res.ok)
             return null;
@@ -530,20 +747,185 @@ export { buildSpawnPlan, quoteForWindowsShell };
  * protection silently disappearing.
  */
 export function inOwnProcessGroup(options) {
-    return { ...options, detached: true };
+    return { ...options, detached: true, windowsHide: true };
 }
 /** Tail of captured installer stderr kept to explain a failure. */
 const INSTALL_DETAIL_MAX_CHARS = 400;
+const KNOWN_NPM_UPDATE_ERROR_CODES = new Set([
+    "E404",
+    "EACCES",
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENOTFOUND",
+    "EPERM",
+    "ETARGET",
+    "ETIMEDOUT",
+]);
+function knownNpmUpdateErrorCode(stderr) {
+    const escape = String.fromCharCode(0x1b);
+    const plainStderr = stderr.replace(new RegExp(`${escape}\\[[0-9;]*m`, "g"), "");
+    const match = /^[ \t]*npm[ \t]+(?:ERR!|error)[ \t]+code[ \t]+([A-Z0-9_]{1,32})[ \t]*$/im.exec(plainStderr);
+    const code = match?.[1]?.toUpperCase();
+    return code && KNOWN_NPM_UPDATE_ERROR_CODES.has(code) ? code : undefined;
+}
+function readKnownNpmDiagnosticCode(filename) {
+    if (!existsSync(filename))
+        return undefined;
+    try {
+        const contents = readFileSync(filename, "utf-8").trim();
+        if (KNOWN_NPM_UPDATE_ERROR_CODES.has(contents))
+            return contents;
+        return knownNpmUpdateErrorCode(contents);
+    }
+    catch (error) {
+        const code = error &&
+            typeof error === "object" &&
+            "code" in error &&
+            typeof error.code === "string" &&
+            /^[A-Z0-9_]{1,32}$/.test(error.code)
+            ? error.code
+            : error instanceof Error
+                ? "Error"
+                : "UnknownError";
+        console.error(chalk.yellow(`Could not read update diagnostic output (${code}).`));
+        return undefined;
+    }
+}
+/** Give a package-manager update ample time without letting it wedge every CLI call. */
+const DEFAULT_UPDATE_TIMEOUT_MS = 30 * 60 * 1_000;
+/** Node clamps longer timer delays to 1ms, so accepting them would invert the deadline. */
+const MAX_UPDATE_TIMEOUT_MS = 2_147_483_647;
+/** Let a well-behaved updater stop before force-killing the rest of its group. */
+const UPDATE_TERMINATE_GRACE_MS = 1_000;
+/** A successful group kill must still yield a close event so the supervisor reaps its child. */
+const UPDATE_REAP_GRACE_MS = 1_000;
+function updateTimeoutMs(env = process.env) {
+    const value = env.HQ_UPDATE_TIMEOUT_MS;
+    if (value === undefined || value.trim() === "")
+        return DEFAULT_UPDATE_TIMEOUT_MS;
+    const parsed = Number(value);
+    if (Number.isInteger(parsed) && parsed > 0 && parsed <= MAX_UPDATE_TIMEOUT_MS) {
+        return parsed;
+    }
+    // Falling back rather than clamping is deliberate: a clamp would silently
+    // substitute a materially different deadline. The warning tells operators
+    // their requested value was rejected before any update begins.
+    console.error(chalk.yellow(`⚠ Ignoring HQ_UPDATE_TIMEOUT_MS=${JSON.stringify(value)}: expected a positive integer no greater than ${MAX_UPDATE_TIMEOUT_MS}ms; using ${DEFAULT_UPDATE_TIMEOUT_MS}ms.`));
+    return DEFAULT_UPDATE_TIMEOUT_MS;
+}
+/**
+ * The actual installer runs in a small asynchronous supervisor, rather than
+ * directly under `spawnSync`. `spawnSync({ timeout })` only signals its direct
+ * child. That is unsafe here because the installer deliberately runs in its
+ * own process group: the leader can exit while its descendants keep the global
+ * store and registry connection alive. The CommonJS file is copied next to the
+ * compiled module for production and is directly runnable from source tests.
+ */
+const UPDATE_COMMAND_SUPERVISOR = fileURLToPath(new URL("./update-command-supervisor.cjs", import.meta.url));
+/** Set while a self-update runs the installer through a copy of the supervisor. */
+let detachedSupervisor = null;
+/** The supervisor script the next install runs under. */
+export function updateSupervisorPath() {
+    return detachedSupervisor ?? UPDATE_COMMAND_SUPERVISOR;
+}
+/**
+ * Copies the supervisor to a temp dir and runs installs through the copy until
+ * disposed. The in-place self-update moves the whole hq-cli package aside
+ * before it starts the installer, and the supervisor ships inside that package
+ * (5.290.0-5.292.0 failed every npm global self-update with MODULE_NOT_FOUND).
+ * The script needs only Node builtins, so the copy runs on its own. Returns
+ * null when the copy cannot be made; the caller then keeps the bundled path.
+ */
+export function detachUpdateSupervisor() {
+    if (detachedSupervisor)
+        return null;
+    let dir;
+    try {
+        dir = mkdtempSync(path.join(os.tmpdir(), "hq-cli-update-supervisor-"));
+        const copy = path.join(dir, "update-command-supervisor.cjs");
+        copyFileSync(UPDATE_COMMAND_SUPERVISOR, copy);
+        detachedSupervisor = copy;
+        const tempDir = dir;
+        return {
+            path: copy,
+            dispose: () => {
+                if (detachedSupervisor === copy)
+                    detachedSupervisor = null;
+                try {
+                    rmSync(tempDir, { recursive: true, force: true });
+                }
+                catch (error) {
+                    const failureClass = error &&
+                        typeof error === "object" &&
+                        "code" in error &&
+                        typeof error.code === "string" &&
+                        /^[A-Z0-9_]{1,32}$/.test(error.code)
+                        ? error.code
+                        : error instanceof Error
+                            ? "Error"
+                            : "UnknownError";
+                    console.error(chalk.yellow(`Could not remove update supervisor temp dir (${failureClass}).`));
+                }
+            },
+        };
+    }
+    catch (error) {
+        const failureClass = error &&
+            typeof error === "object" &&
+            "code" in error &&
+            typeof error.code === "string" &&
+            /^[A-Z0-9_]{1,32}$/.test(error.code)
+            ? error.code
+            : error instanceof Error
+                ? "Error"
+                : "UnknownError";
+        console.error(chalk.yellow(`Could not copy update supervisor (${failureClass}).`));
+        if (dir)
+            rmSync(dir, { recursive: true, force: true });
+        return null;
+    }
+}
+function readSupervisorSpawnError(errorMarker) {
+    try {
+        const value = JSON.parse(readFileSync(errorMarker, "utf-8"));
+        const code = typeof value.code === "string" ? value.code : undefined;
+        const detail = typeof value.detail === "string" ? value.detail : undefined;
+        return code === undefined && detail === undefined ? undefined : { code, detail };
+    }
+    catch {
+        return undefined;
+    }
+}
 export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true && process.stderr.isTTY === true) {
     if (verbose && isTty) {
+        const dir = mkdtempSync(path.join(os.tmpdir(), "hq-cli-install-"));
+        const timeoutMarker = path.join(dir, "timed-out");
+        const errorMarker = path.join(dir, "spawn-error.json");
+        const diagnosticMarker = path.join(dir, "npm-error-code");
         return {
             stdio: ["ignore", "inherit", "inherit"],
             stderrTail: () => "",
-            dispose: () => { },
+            diagnosticCode: () => readKnownNpmDiagnosticCode(diagnosticMarker),
+            diagnosticMarker,
+            timeoutMarker,
+            errorMarker,
+            timedOut: () => existsSync(timeoutMarker),
+            spawnError: () => readSupervisorSpawnError(errorMarker),
+            dispose: () => {
+                try {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+                catch {
+                    // Best-effort cleanup of the supervisor's timeout marker.
+                }
+            },
         };
     }
     const dir = mkdtempSync(path.join(os.tmpdir(), "hq-cli-install-"));
     const errPath = path.join(dir, "stderr.log");
+    const timeoutPath = path.join(dir, "timed-out");
+    const errorPath = path.join(dir, "spawn-error.json");
     const out = openSync(path.join(dir, "stdout.log"), "a");
     const err = openSync(errPath, "a");
     return {
@@ -556,6 +938,11 @@ export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true
                 return "";
             }
         },
+        diagnosticCode: () => readKnownNpmDiagnosticCode(errPath),
+        timeoutMarker: timeoutPath,
+        errorMarker: errorPath,
+        timedOut: () => existsSync(timeoutPath),
+        spawnError: () => readSupervisorSpawnError(errorPath),
         dispose: () => {
             for (const fd of [out, err]) {
                 try {
@@ -574,13 +961,29 @@ export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true
         },
     };
 }
-export function runUpdateCommand(cmd, args, env) {
-    const output = openInstallOutput(true);
+export function runSupervisedUpdateCommand(cmd, args, output, env) {
     try {
         const plan = buildSpawnPlan(cmd, args);
-        const result = spawnSync(plan.cmd, plan.args, inOwnProcessGroup({
+        const timeoutMs = updateTimeoutMs(env);
+        // The outer sync spawn waits only for our supervisor. The supervisor owns
+        // the wall-clock deadline, sends TERM to the updater's whole process group,
+        // waits briefly, sends KILL to survivors, and waits for its direct child so
+        // the completed result leaves no zombie behind.
+        const result = spawnSync(process.execPath, [
+            updateSupervisorPath(),
+            JSON.stringify({
+                cmd: plan.cmd,
+                args: plan.args,
+                shell: plan.shell,
+                timeoutMs,
+                graceMs: UPDATE_TERMINATE_GRACE_MS,
+                reapMs: UPDATE_REAP_GRACE_MS,
+                timeoutMarker: output.timeoutMarker,
+                errorMarker: output.errorMarker,
+                diagnosticMarker: output.diagnosticMarker,
+            }),
+        ], inOwnProcessGroup({
             stdio: output.stdio,
-            shell: plan.shell,
             ...(env ? { env } : {}),
         }));
         // spawnSync reports a missing executable via `error`, not a throw.
@@ -588,12 +991,34 @@ export function runUpdateCommand(cmd, args, env) {
             const code = result.error.code;
             return { ok: false, code, detail: result.error.message };
         }
+        if (output.timedOut()) {
+            const command = [cmd, ...args].join(" ");
+            const supervisorError = output.spawnError();
+            const detail = [
+                `timed out after ${timeoutMs}ms: ${command}`,
+                supervisorError?.detail,
+            ]
+                .filter(Boolean)
+                .join("; ");
+            console.error(chalk.red(`✗ Update ${detail}.`));
+            return { ok: false, code: "ETIMEDOUT", detail };
+        }
+        const spawnedError = output.spawnError();
+        if (spawnedError) {
+            return {
+                ok: false,
+                code: spawnedError.code,
+                detail: spawnedError.detail ?? "failed to start updater",
+            };
+        }
         if (result.status !== 0) {
             // When output went to a file rather than the user's terminal, its tail is
             // the only explanation anyone will ever see for this failure.
             const captured = output.stderrTail();
             return {
                 ok: false,
+                diagnosticCode: output.diagnosticCode(),
+                failureKind: "package_manager_exit",
                 detail: captured || `exit ${result.status ?? "signal"}`,
             };
         }
@@ -606,6 +1031,12 @@ export function runUpdateCommand(cmd, args, env) {
             detail: err instanceof Error ? err.message : String(err),
         };
     }
+}
+export function runUpdateCommand(cmd, args, env) {
+    const output = openInstallOutput(true);
+    try {
+        return runSupervisedUpdateCommand(cmd, args, output, env);
+    }
     finally {
         output.dispose();
     }
@@ -656,7 +1087,9 @@ function manualUpdateCommand(install, decision) {
  * remains for callers that pass no handler.
  */
 function nudgeUpdateRecommended(decision, install = resolveRunningInstall()) {
-    const msg = chalk.yellow(`⚠ A new version of hq-cli is available: ${decision.latestVersion} (current: ${decision.currentVersion}).`);
+    if (!isNewerVersion(decision.latestVersion, CLI_VERSION))
+        return;
+    const msg = chalk.yellow(`⚠ A new version of hq-cli is available: ${decision.latestVersion} (current: ${CLI_VERSION}).`);
     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
@@ -707,6 +1140,44 @@ export function resolveHqOnPath() {
         return null;
     }
 }
+/**
+ * Pull the CLI version out of `hq --version` / `hq version` output.
+ *
+ * Compare CLI to CLI. Never take the first version-shaped token: 5.119.13–
+ * 5.121.0 printed `HQ <core>` above `CLI <cli>`, and scraping the HQ line
+ * made a successful install look like a PATH shadow.
+ *
+ * Accepts:
+ *   - bare semver (historical `--version`, and `--version` again after this fix)
+ *   - labelled `CLI x.y.z` (those 5.119.13–5.121.0 builds)
+ *   - JSON `{ "cli": "x.y.z", ... }` from `--json`
+ */
+export function parseReportedCliVersion(stdout) {
+    const text = stdout.trim();
+    if (!text)
+        return null;
+    if (text.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed.cli === "string" && parsed.cli.trim()) {
+                return parsed.cli.trim();
+            }
+        }
+        catch {
+            // Fall through to labelled / bare parsers.
+        }
+    }
+    const labelled = /^[ \t]*CLI[ \t]+(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/m.exec(text);
+    if (labelled)
+        return labelled[1];
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length === 1)
+        return lines[0];
+    return null;
+}
 /** `<bin> --version` output (trimmed), or null on any failure/timeout. */
 export function probeCliVersion(bin) {
     try {
@@ -716,8 +1187,7 @@ export function probeCliVersion(bin) {
         });
         if (result.error || result.status !== 0)
             return null;
-        const out = (result.stdout ?? "").trim();
-        return out || null;
+        return parseReportedCliVersion(result.stdout ?? "");
     }
     catch {
         return null;
@@ -732,9 +1202,10 @@ export function probeCliVersion(bin) {
  * 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.
+ * updater-war this fix exists for. Detect a stale PATH result here, identify a
+ * distinct package managed by a supported global manager before calling it a
+ * shadow, 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.
@@ -754,12 +1225,6 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
         }
         if (reported === targetVersion)
             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
@@ -774,6 +1239,36 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
             semver.gte(reportedSemver, targetSemver)) {
             return true;
         }
+        const runningInstall = (deps.currentInstall ?? resolveRunningInstall)();
+        const packageRoot = (deps.packageRootForBin ?? findPackageRootForExecutable)(bin);
+        const manager = packageRoot &&
+            runningInstall.packageRoot &&
+            !samePath(packageRoot, runningInstall.packageRoot)
+            ? globalInstallManagerForPath(bin, packageRoot)
+            : null;
+        let detail;
+        if (manager) {
+            const removeCommand = manager === "pnpm"
+                ? `pnpm remove -g ${CLI_NAME}`
+                : manager === "bun"
+                    ? `bun remove -g ${CLI_NAME}`
+                    : `npm uninstall -g ${CLI_NAME}`;
+            let realPath = bin;
+            try {
+                realPath = realpathSync(bin);
+            }
+            catch {
+                // Keep the shell-resolved path when a platform shim is not canonicalizable.
+            }
+            detail =
+                `PATH resolves ${realPath} at version ${reported} (manager: ${manager}); ` +
+                    `that second hq-cli install is shadowing the managed one. Remove it with \`${removeCommand}\`.`;
+        }
+        else {
+            detail =
+                `PATH resolves ${bin} at version ${reported}, but no second managed hq-cli install was confirmed.`;
+        }
+        console.error(chalk.yellow(`⚠ hq updated to ${targetVersion} but did not converge: ${detail}`));
         return false;
     }
     catch {
@@ -796,9 +1291,13 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
  * Exit codes:
  *   0 — update succeeded; user must rerun their command
  *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
+ *
+ * A timed-out updater is the exception: it has been forcibly reaped, so the
+ * gate returns and lets the user's command run on the current version.
  */
 function enforceUpdateRequired(decision, deps = {}) {
-    const banner = chalk.red.bold(`✗ hq-cli ${decision.currentVersion} is below the minimum required version (${decision.minVersion}).`);
+    currentVersionGatePhase = "preflight";
+    const banner = chalk.red.bold(`✗ hq-cli ${CLI_VERSION} is below the minimum required version (${decision.minVersion}).`);
     console.error(banner);
     if (decision.message)
         console.error(chalk.dim(`  ${decision.message}`));
@@ -824,8 +1323,8 @@ function enforceUpdateRequired(decision, deps = {}) {
     // 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}.`));
+    if (!isNewerVersion(decision.latestVersion, CLI_VERSION)) {
+        console.error(chalk.red(`  Refusing to update: the offered version ${decision.latestVersion} is not newer than the running ${CLI_VERSION}.`));
         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);
     }
@@ -848,17 +1347,30 @@ function enforceUpdateRequired(decision, deps = {}) {
         console.error(chalk.dim("  Another hq updater is already installing (update lock held); continuing on the current version."));
         return;
     }
-    let exitCode;
+    currentVersionGatePhase = "lock_acquired";
+    let attempt;
     try {
-        exitCode = attemptRequiredUpdate(decision, deps, install);
+        attempt = 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.
+    catch (error) {
         lock.release();
+        throw error;
     }
-    process.exit(exitCode);
+    if (attempt instanceof Promise) {
+        return attempt.then((exitCode) => {
+            lock.release();
+            if (exitCode !== "continue")
+                process.exit(exitCode);
+        }, (error) => {
+            lock.release();
+            throw error;
+        });
+    }
+    // `process.exit` skips `finally`, so release explicitly before exiting.
+    lock.release();
+    if (attempt === "continue")
+        return;
+    process.exit(attempt);
 }
 /**
  * The install attempt itself (npm/pnpm/bun routing, stale-partial cleanup,
@@ -870,6 +1382,7 @@ function attemptRequiredUpdate(decision, deps, install) {
     const command = decision.updateCommand;
     const isManagedOutsideNpm = install.manager !== "npm";
     const prefix = install.prefix;
+    const stagedNpmPrefix = Boolean(!isManagedOutsideNpm && prefix && /\s/.test(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.
@@ -899,6 +1412,8 @@ function attemptRequiredUpdate(decision, deps, install) {
     // npm/bun and when PNPM_HOME is already set.
     const updateEnv = pnpmUpdateEnv(install);
     let result;
+    let noticeFlush = null;
+    currentVersionGatePhase = "installer_running";
     if (isManagedOutsideNpm) {
         console.error(chalk.dim(`  Detected a ${install.manager}-managed global install; updating with ${install.manager}`));
         console.error(chalk.dim(`  Running: ${primaryCmd} ${primaryArgs.join(" ")}`));
@@ -906,8 +1421,20 @@ function attemptRequiredUpdate(decision, deps, install) {
     }
     else if (prefix) {
         console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
-        console.error(chalk.dim(`  Running: npm ${primaryArgs.join(" ")}`));
-        result = performUpdateCommand("npm", primaryArgs, runner);
+        if (stagedNpmPrefix) {
+            console.error(chalk.dim("  Building in a space-free temporary prefix before activation."));
+            const installStaged = deps.installNpmPackageStaged;
+            if (!installStaged) {
+                result = { ok: false, detail: "staged npm installer was not loaded" };
+            }
+            else {
+                result = installStaged(prefix, LATEST_PACKAGE_SPEC, runner);
+            }
+        }
+        else {
+            console.error(chalk.dim(`  Running: npm ${primaryArgs.join(" ")}`));
+            result = performUpdateCommand("npm", primaryArgs, runner);
+        }
     }
     else {
         console.error(chalk.dim(`  Running: ${command}`));
@@ -923,7 +1450,7 @@ function attemptRequiredUpdate(decision, deps, install) {
     // artifacts and retry the install ONCE. Guarded on `cleaned.length > 0` so a
     // plain EACCES on an otherwise-healthy prefix falls straight through to the
     // sudo retry below without a redundant reinstall attempt.
-    if (!result.ok && prefix) {
+    if (!result.ok && result.code !== "ETIMEDOUT" && prefix && !stagedNpmPrefix) {
         const cleaner = deps.cleanStale ?? cleanStalePartialInstall;
         const cleaned = cleaner(prefix);
         if (cleaned.length > 0) {
@@ -943,20 +1470,37 @@ function attemptRequiredUpdate(decision, deps, install) {
     // Never for pnpm or Bun: elevation changes the package manager's global home,
     // leaving the user's shim untouched while reporting success. A failed
     // non-npm update must surface instead.
-    if (!result.ok && primaryCmd && !isManagedOutsideNpm) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== "win32" &&
+        !result.ok &&
+        result.code !== "ETIMEDOUT" &&
+        primaryCmd &&
+        !isManagedOutsideNpm &&
+        !stagedNpmPrefix) {
         console.error(chalk.dim(`  Update failed unprivileged; retrying with: sudo -n ${primaryCmd} ${primaryArgs.join(" ")}`));
         const sudoResult = performUpdateCommand("sudo", ["-n", primaryCmd, ...primaryArgs], runner);
         if (sudoResult.ok)
             result = sudoResult;
     }
     if (!result.ok) {
+        currentVersionGatePhase = "failed";
         console.error(chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`));
-        // A root-owned global prefix the running user cannot write is the agent-box
-        // case: even the `sudo -n` retry above cannot help without passwordless
-        // sudo, so name the wall plainly rather than leaving `exit 75` to read as a
-        // generic failure. Only for npm-prefix installs (pnpm/Bun route elsewhere).
-        if (!isManagedOutsideNpm && prefix && !isPrefixWritable(prefix)) {
+        // If the npm prefix is still unwritable after the unprivileged and sudo
+        // attempts, explain the permission wall plainly instead of leaving exit 75
+        // as a generic failure. Only applies to npm-managed installs.
+        const npmPrefixNotWritable = !isManagedOutsideNpm &&
+            prefix &&
+            install.packageRoot &&
+            !(deps.canWriteNpmInstall ?? ((resolved) => canWriteNpmInstall(resolved.prefix, resolved.packageRoot)))(install);
+        if (npmPrefixNotWritable) {
             console.error(chalk.yellow(`  ${nonWritablePrefixNote(prefix)}`));
+            noticeFlush = captureNonWritableNpmPrefixNotice({
+                fromVersion: CLI_VERSION,
+                targetVersion: decision.latestVersion,
+                install,
+                env: process.env,
+                homeDir: deps.homeDir,
+            });
         }
         // The package manager itself is missing from this environment — the usual
         // cause is a minimal-PATH parent (launchd, cron, a bare systemd unit) that
@@ -973,25 +1517,37 @@ function attemptRequiredUpdate(decision, deps, install) {
         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.)`));
         }
-        return 75;
+        // The self-update is allowed to fail, but a deadline expiry must not turn
+        // into a second, indefinite denial of the user's command. The supervisor
+        // either reaped the group or recorded why the OS denied that signal; in
+        // neither case did an update land. Continue on the current CLI rather than
+        // pretending it did or aborting the command that caused the gate to run.
+        if (result.code === "ETIMEDOUT") {
+            console.error(chalk.dim("  Continuing on the current hq-cli version."));
+            return "continue";
+        }
+        return noticeFlush ? noticeFlush.then(() => 75) : 75;
     }
     // Read-your-writes: a "successful" install into the npm prefix does not
     // 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.
+    currentVersionGatePhase = "verifying";
     const converged = (deps.checkConvergence ?? checkUpdateConvergence)(decision.latestVersion);
     if (converged === false) {
+        currentVersionGatePhase = "failed";
         console.error(chalk.red(`✗ Update did not take effect: \`hq\` on PATH still resolves a different build than ${decision.latestVersion}.`));
         return 75;
     }
+    currentVersionGatePhase = "complete";
     console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
     return 0;
 }
-export async function enforceVersionGate(onUpdateRecommended) {
+export async function enforceVersionGate(onUpdateRecommended, options = {}) {
     if (isOptedOut())
         return "continue";
-    const decision = await fetchVersionDecision();
+    const decision = await fetchVersionDecision(options.timeoutMs);
     if (!decision)
         return "continue"; // best-effort: silent on any failure
     if (!decision.updateRequired && !decision.updateRecommended)
@@ -1000,9 +1556,18 @@ export async function enforceVersionGate(onUpdateRecommended) {
     // neither downstream path repeats it.
     const install = resolveRunningInstall();
     if (decision.updateRequired) {
+        // Load the staged installer only for the uncommon spaced npm-prefix path.
+        // The version gate is imported during every CLI startup, including native
+        // fast routes, so eagerly importing this filesystem-heavy module adds cost
+        // to commands that never update.
+        const installNpmPackageStaged = install.manager === "npm" && install.prefix && /\s/.test(install.prefix)
+            ? (await import("./staged-npm-install.js")).installNpmPackageStaged
+            : undefined;
         // 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 });
+        const requiredUpdate = enforceUpdateRequired(decision, { resolveInstall: () => install, installNpmPackageStaged });
+        if (requiredUpdate)
+            await requiredUpdate;
         return "continue";
     }
     if (decision.updateRecommended) {
@@ -1023,11 +1588,18 @@ export async function enforceVersionGate(onUpdateRecommended) {
  * force-upgraded.
  */
 export function shouldSkipGate(argv) {
-    return argv.some((a) => a === "--version" || a === "-V" || a === "-v" || a === "--help" || a === "-h");
+    return argv.some((a) => a === "--version" ||
+        a === "-V" ||
+        a === "-v" ||
+        a === "--help" ||
+        a === "-h" ||
+        a === "version");
 }
 export const __test__ = {
     CLIENT_ID,
+    getVersionGatePhase,
     CONVERGENCE_TIMEOUT_MS,
+    DEFAULT_UPDATE_TIMEOUT_MS,
     ENDPOINT_PATH,
     FETCH_TIMEOUT_MS,
     checkUpdateConvergence,
@@ -1037,6 +1609,8 @@ export const __test__ = {
     buildPnpmInstallArgv,
     buildPrefixedInstallArgv,
     buildSpawnPlan,
+    canWriteNpmInstall,
+    claimNonWritableNpmPrefixNotice,
     cleanStalePartialInstall,
     derivePnpmHome,
     enforceUpdateRequired,
@@ -1058,5 +1632,6 @@ export const __test__ = {
     resolveRunningInstall,
     resolveRunningManager,
     resolveRunningPrefix,
+    updateTimeoutMs,
 };
 //# sourceMappingURL=version-gate.js.map