@indigoai-us/hq-cli 5.300.0 → 5.301.0

package/dist/utils/staged-npm-install.js

@@ -0,0 +1,264 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const PACKAGE_NAME = "@indigoai-us/hq-cli";
+const RANDOM_HEX_BYTES = 6;
+function packageRoot(prefix, platform) {
+    const modules = platform === "win32"
+        ? path.join(prefix, "node_modules")
+        : path.join(prefix, "lib", "node_modules");
+    return path.join(modules, "@indigoai-us", "hq-cli");
+}
+function binsFromPackageJson(packageDir) {
+    const parsed = JSON.parse(readFileSync(path.join(packageDir, "package.json"), "utf8"));
+    if (parsed.name !== PACKAGE_NAME)
+        throw new Error("staged npm package name did not match hq-cli");
+    const bins = typeof parsed.bin === "string"
+        ? { hq: parsed.bin }
+        : parsed.bin && typeof parsed.bin === "object" && !Array.isArray(parsed.bin)
+            ? parsed.bin
+            : {};
+    for (const [name, target] of Object.entries(bins)) {
+        if (!name || name === "." || name === ".." || /[\\/]/.test(name)) {
+            throw new Error(`invalid executable name in staged package: ${name}`);
+        }
+        if (typeof target !== "string" || path.isAbsolute(target)) {
+            throw new Error(`invalid executable target in staged package: ${name}`);
+        }
+        const resolved = path.resolve(packageDir, target);
+        if (resolved !== packageDir && !resolved.startsWith(`${packageDir}${path.sep}`)) {
+            throw new Error(`executable target escapes staged package: ${name}`);
+        }
+    }
+    return bins;
+}
+function oldBinNames(packageDir) {
+    try {
+        return Object.keys(binsFromPackageJson(packageDir));
+    }
+    catch {
+        return [];
+    }
+}
+function temporaryRoot() {
+    const candidates = [os.tmpdir(), process.platform === "win32" ? `${process.env.SystemDrive ?? "C:"}\\Temp` : "/tmp"];
+    const root = candidates.find((candidate) => !/\s/.test(candidate) && existsSync(candidate));
+    if (!root)
+        throw new Error("no writable temporary directory without spaces is available");
+    return mkdtempSync(path.join(root, "hq-cli-update-"));
+}
+function randomSuffix() {
+    return randomBytes(RANDOM_HEX_BYTES).toString("hex");
+}
+function bestEffortRemove(target) {
+    if (!target)
+        return;
+    try {
+        rmSync(target, { recursive: true, force: true });
+    }
+    catch (error) {
+        console.warn("[hq-cli-update] could not remove staged install artifact", {
+            path: target,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Build hq-cli in a space-free temporary npm prefix, then replace the package
+ * and its executable links under the real prefix only after npm succeeds.
+ * Existing files are held beside their destinations until activation completes,
+ * so failed installs and failed activation restore the prior working tree.
+ */
+export function installNpmPackageStaged(prefix, packageSpec, runner, platform = process.platform, activate = activateStagedNpmPackage) {
+    let stagePrefix;
+    try {
+        stagePrefix = temporaryRoot();
+        const npmResult = runner("npm", ["install", "-g", "--prefix", stagePrefix, packageSpec], { ...process.env, HQ_STAGED_INSTALL: "1" });
+        if (!npmResult.ok)
+            return npmResult;
+        const activation = activate(prefix, stagePrefix, platform);
+        if (activation.ok || activation.code !== "EACCES" || platform === "win32")
+            return activation;
+        // A spaced, root-owned npm prefix must still be buildable without passing
+        // that prefix to npm/node-gyp. Re-run only the filesystem activation as
+        // root; the package build remains in the space-free user-owned temp path.
+        const elevated = runner("sudo", [
+            "-n",
+            "npm",
+            "exec",
+            "--",
+            process.execPath,
+            fileURLToPath(import.meta.url),
+            "--activate",
+            prefix,
+            stagePrefix,
+            platform,
+        ]);
+        return elevated.ok
+            ? { ok: true }
+            : {
+                ...elevated,
+                detail: elevated.detail ?? "could not activate the staged npm install with sudo",
+            };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            detail: error instanceof Error ? error.message : String(error),
+            code: error?.code,
+        };
+    }
+    finally {
+        bestEffortRemove(stagePrefix);
+    }
+}
+/** Atomically replace a package already built under a temporary npm prefix. */
+export function activateStagedNpmPackage(prefix, stagePrefix, platform = process.platform) {
+    let candidatePackage;
+    let stagedBins;
+    let backupBins;
+    let backupPackage;
+    let packageBackedUp = false;
+    let packageActivated = false;
+    const backedUpBins = [];
+    const activatedBins = [];
+    try {
+        const stagedPackage = packageRoot(stagePrefix, platform);
+        const targetPackage = packageRoot(prefix, platform);
+        const stageBinDir = platform === "win32" ? stagePrefix : path.join(stagePrefix, "bin");
+        const targetBinDir = platform === "win32" ? prefix : path.join(prefix, "bin");
+        const bins = binsFromPackageJson(stagedPackage);
+        const suffix = randomSuffix();
+        const targetScopeDir = path.dirname(targetPackage);
+        mkdirSync(targetScopeDir, { recursive: true });
+        mkdirSync(targetBinDir, { recursive: true });
+        candidatePackage = path.join(targetScopeDir, `.hq-cli-next-${suffix}`);
+        cpSync(stagedPackage, candidatePackage, { recursive: true, verbatimSymlinks: true });
+        stagedBins = path.join(targetBinDir, `.hq-cli-bins-next-${suffix}`);
+        backupBins = path.join(targetBinDir, `.hq-cli-bins-backup-${suffix}`);
+        mkdirSync(stagedBins);
+        mkdirSync(backupBins);
+        backupPackage = path.join(targetScopeDir, `.hq-cli-backup-${suffix}`);
+        const names = new Set([...Object.keys(bins), ...oldBinNames(targetPackage)]);
+        for (const name of names) {
+            const entry = bins[name];
+            if (entry === undefined)
+                continue;
+            const executable = path.join(targetPackage, entry);
+            if (platform === "win32") {
+                for (const extension of ["", ".cmd", ".ps1"]) {
+                    const stagedFile = path.join(stageBinDir, `${name}${extension}`);
+                    if (!existsSync(stagedFile))
+                        continue;
+                    const stagedText = readFileSync(stagedFile, "utf8");
+                    const relocated = stagedText
+                        .split(stagePrefix).join(prefix)
+                        .split(stagePrefix.replace(/\\/g, "/")).join(prefix.replace(/\\/g, "/"));
+                    writeFileSync(path.join(stagedBins, `${name}${extension}`), relocated, {
+                        mode: extension === ".cmd" || extension === "" ? 0o755 : 0o644,
+                    });
+                }
+            }
+            else {
+                const stagedFile = path.join(stageBinDir, name);
+                if (!existsSync(stagedFile))
+                    throw new Error(`npm did not create the ${name} executable link`);
+                if (!existsSync(executable))
+                    throw new Error(`staged executable target is missing for ${name}`);
+                symlinkSync(path.relative(targetBinDir, executable), path.join(stagedBins, name));
+            }
+        }
+        if (existsSync(targetPackage)) {
+            renameSync(targetPackage, backupPackage);
+            packageBackedUp = true;
+        }
+        renameSync(candidatePackage, targetPackage);
+        packageActivated = true;
+        for (const name of names) {
+            for (const extension of platform === "win32" ? ["", ".cmd", ".ps1"] : [""]) {
+                const filename = `${name}${extension}`;
+                const target = path.join(targetBinDir, filename);
+                const staged = path.join(stagedBins, filename);
+                if (existsSync(target) || lstatExists(target)) {
+                    const backup = path.join(backupBins, filename);
+                    renameSync(target, backup);
+                    backedUpBins.push({ target, backup });
+                }
+                if (existsSync(staged) || lstatExists(staged)) {
+                    renameSync(staged, target);
+                    activatedBins.push(target);
+                }
+            }
+        }
+        bestEffortRemove(packageBackedUp ? backupPackage : undefined);
+        bestEffortRemove(backupBins);
+        return { ok: true };
+    }
+    catch (error) {
+        for (const target of activatedBins.reverse())
+            bestEffortRemove(target);
+        for (const item of backedUpBins.reverse()) {
+            if (existsSync(item.backup) || lstatExists(item.backup)) {
+                try {
+                    renameSync(item.backup, item.target);
+                }
+                catch (restoreError) {
+                    console.error("[hq-cli-update] could not restore previous executable link", {
+                        path: item.target,
+                        error: restoreError instanceof Error ? restoreError.message : String(restoreError),
+                    });
+                }
+            }
+        }
+        if (packageActivated)
+            bestEffortRemove(packageRoot(prefix, platform));
+        if (packageBackedUp && backupPackage && existsSync(backupPackage)) {
+            try {
+                renameSync(backupPackage, packageRoot(prefix, platform));
+            }
+            catch (restoreError) {
+                console.error("[hq-cli-update] could not restore previous package", {
+                    path: packageRoot(prefix, platform),
+                    error: restoreError instanceof Error ? restoreError.message : String(restoreError),
+                });
+            }
+        }
+        return {
+            ok: false,
+            detail: error instanceof Error ? error.message : String(error),
+            code: error?.code,
+        };
+    }
+    finally {
+        bestEffortRemove(candidatePackage);
+        bestEffortRemove(stagedBins);
+        bestEffortRemove(backupBins);
+        if (!packageBackedUp)
+            bestEffortRemove(backupPackage);
+    }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === "--activate") {
+    const [prefix, stagePrefix, platform] = process.argv.slice(3);
+    if (!prefix || !stagePrefix) {
+        console.error("usage: staged-npm-install.js --activate <prefix> <stage-prefix> [platform]");
+        process.exit(2);
+    }
+    else {
+        const result = activateStagedNpmPackage(prefix, stagePrefix, platform || process.platform);
+        if (!result.ok)
+            console.error(result.detail ?? "staged npm activation failed");
+        process.exit(result.ok ? 0 : 1);
+    }
+}
+function lstatExists(target) {
+    try {
+        lstatSync(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=staged-npm-install.js.map

package/dist/utils/update-command-supervisor.cjs

@@ -3,6 +3,18 @@
 const { spawn: nativeSpawn } = require("node:child_process");
 const fs = require("node:fs");
 
+const KNOWN_NPM_ERROR_CODES = new Set([
+  "E404",
+  "EACCES",
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENOTFOUND",
+  "EPERM",
+  "ETARGET",
+  "ETIMEDOUT",
+]);
+
 function windowsTaskkillArgs(pid) {
   return ["/PID", String(pid), "/T", "/F"];
 }
@@ -24,6 +36,14 @@ function writeMarker(filename, contents, log) {
   }
 }
 
+function npmErrorCodeFromLine(line) {
+  const escape = String.fromCharCode(0x1b);
+  const plainLine = line.replace(new RegExp(`${escape}\\[[0-9;]*m`, "g"), "").trim();
+  const match = /^npm\s+(?:ERR!|error)\s+code\s+([A-Z0-9_]{1,32})$/i.exec(plainLine);
+  const code = match && match[1].toUpperCase();
+  return code && KNOWN_NPM_ERROR_CODES.has(code) ? code : undefined;
+}
+
 /**
  * Spawn and supervise one package-manager update. On POSIX the detached child
  * is its own process-group leader, so signals reach the leader and every
@@ -50,6 +70,31 @@ function runUpdateSupervisor(config, dependencies = {}) {
   let timedOut = false;
   let childClosed = false;
   let treeTerminationConfirmed = false;
+  let stderrLineBuffer = "";
+  let diagnosticRecorded = false;
+
+  function inspectNpmStderrLine(line) {
+    if (diagnosticRecorded || !config.diagnosticMarker) return;
+    const code = npmErrorCodeFromLine(line);
+    if (!code) return;
+    writeMarker(config.diagnosticMarker, code, log);
+    diagnosticRecorded = true;
+  }
+
+  function inspectNpmStderrChunk(chunk) {
+    if (diagnosticRecorded || !config.diagnosticMarker) return;
+    const lines = `${stderrLineBuffer}${chunk.toString("utf8")}`.split(/\r?\n/);
+    stderrLineBuffer = lines.pop() || "";
+    for (const line of lines) inspectNpmStderrLine(line);
+    if (stderrLineBuffer.length > 128) {
+      stderrLineBuffer = stderrLineBuffer.slice(-128);
+    }
+  }
+
+  function flushNpmStderrLine() {
+    if (stderrLineBuffer) inspectNpmStderrLine(stderrLineBuffer);
+    stderrLineBuffer = "";
+  }
 
   function clear(timer) {
     if (timer !== undefined) clearTimer(timer);
@@ -141,7 +186,7 @@ function runUpdateSupervisor(config, dependencies = {}) {
   try {
     child = spawn(config.cmd, config.args, {
       detached: true,
-      stdio: ["ignore", "inherit", "inherit"],
+      stdio: ["ignore", "inherit", config.diagnosticMarker ? "pipe" : "inherit"],
       shell: config.shell,
     });
   } catch (error) {
@@ -156,6 +201,7 @@ function runUpdateSupervisor(config, dependencies = {}) {
   });
   child.once("close", (code) => {
     childClosed = true;
+    flushNpmStderrLine();
     if (!timedOut) {
       finish(code === 0 ? 0 : (code ?? 1));
       return;
@@ -163,6 +209,12 @@ function runUpdateSupervisor(config, dependencies = {}) {
     if (treeTerminationConfirmed) timeoutAfterReap();
   });
 
+  if (config.diagnosticMarker && child.stderr) {
+    child.stderr.on("data", inspectNpmStderrChunk);
+    child.stderr.on("end", flushNpmStderrLine);
+    child.stderr.pipe(process.stderr);
+  }
+
   deadlineTimer = setTimer(() => {
     if (finished) return;
     timedOut = true;

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

@@ -256,6 +256,9 @@ export type UpdateResult = {
     ok: boolean;
     detail?: string;
     code?: string;
+    /** Sanitized installer error code for diagnostics; never drives retry or exit behavior. */
+    diagnosticCode?: string;
+    failureKind?: "package_manager_exit";
 };
 type UpdateRunner = (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
 export { buildSpawnPlan, quoteForWindowsShell };
@@ -323,6 +326,10 @@ export interface InstallOutput {
     stdio: ("ignore" | "inherit" | number)[];
     /** Captured stderr tail, or "" when output was inherited by a terminal. */
     stderrTail: () => string;
+    /** Allowlisted npm error code from captured stderr, when output was captured. */
+    diagnosticCode: () => string | undefined;
+    /** Supervisor marker used to inspect npm errors while forwarding terminal stderr. */
+    diagnosticMarker?: string;
     /** Private side-channel from the supervisor, kept out of installer output. */
     timeoutMarker: string;
     /** Private spawn-error side-channel that preserves the prior result contract. */
@@ -414,6 +421,7 @@ interface EnforceUpdateDeps {
      * returns nothing still exercises the success path.
      */
     checkConvergence?: (targetVersion: string) => boolean | void;
+    installNpmPackageStaged?: typeof import("./staged-npm-install.js").installNpmPackageStaged;
 }
 /**
  * Hard enforcement when the server says we're below `minVersion`. Print a

package/dist/utils/version-gate.js

@@ -28,7 +28,6 @@
  * to silence both check + gate).
  */
 import { spawnSync } from "node:child_process";
-import { installPathCompatibilityEnabled } from "../lib/install-path-compatibility-flag.js";
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
 import { accessSync, closeSync, constants as fsConstants, copyFileSync, existsSync, mkdtempSync, openSync, readdirSync, realpathSync, readFileSync, rmSync, } from "node:fs";
 import os from "node:os";
@@ -106,8 +105,7 @@ function findPackageRootForExecutable(bin) {
             path.join(storeRoot, "node_modules", ...packageSegments),
         ];
         // pnpm v11 adds a hash between its global store version and node_modules.
-        // Its `vN` layout remains subject to the existing compatibility gate unless
-        // PNPM_HOME itself authorizes the global root via isPnpmManagedPackageDir.
+        // Its documented `vN` global layout is recognized unconditionally below.
         if (/^v\d+$/.test(storeVersion)) {
             try {
                 for (const hash of readdirSync(storeRoot)) {
@@ -122,7 +120,7 @@ function findPackageRootForExecutable(bin) {
             const packageRoot = findCliPackageRoot(candidate);
             if (packageRoot &&
                 samePath(packageRoot, candidate) &&
-                isPnpmManagedPackageDir(packageRoot, installPathCompatibilityEnabled())) {
+                isPnpmManagedPackageDir(packageRoot, true)) {
                 return packageRoot;
             }
         }
@@ -145,7 +143,7 @@ function samePath(left, right) {
         : a === b;
 }
 function globalInstallManagerForPath(bin, packageRoot) {
-    if (isPnpmManagedPackageDir(packageRoot, installPathCompatibilityEnabled())) {
+    if (isPnpmManagedPackageDir(packageRoot, true)) {
         return "pnpm";
     }
     if (isBunManagedPackageDir(packageRoot))
@@ -209,13 +207,13 @@ 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, acceptVersionPrefixedGlobalDir = false) {
+export function isPnpmManagedPackageDir(pkgDir, acceptVersionPrefixedGlobalDir = true) {
     const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
     const segments = normalized.split("/").filter(Boolean);
     // pnpm through v10 uses `global/<digits>`; pnpm v11+ uses
-    // `global/v<major>`. Keep the newer form behind the default-off rollout
-    // flag, and require a documented version segment so `global/next` or a
-    // `v11` directory elsewhere cannot be mistaken for a global install.
+    // `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")
             continue;
@@ -355,7 +353,7 @@ export function resolveRunningInstall() {
         const packageRoot = findRunningPackageRoot();
         if (!packageRoot)
             return { manager: "npm", prefix: null, packageRoot: null };
-        if (isPnpmManagedPackageDir(packageRoot, installPathCompatibilityEnabled())) {
+        if (isPnpmManagedPackageDir(packageRoot, true)) {
             return { manager: "pnpm", prefix: null, packageRoot };
         }
         if (isBunManagedPackageDir(packageRoot)) {
@@ -643,6 +641,47 @@ export function inOwnProcessGroup(options) {
 }
 /** 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. */
@@ -753,9 +792,12 @@ export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true
         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: () => "",
+            diagnosticCode: () => readKnownNpmDiagnosticCode(diagnosticMarker),
+            diagnosticMarker,
             timeoutMarker,
             errorMarker,
             timedOut: () => existsSync(timeoutMarker),
@@ -786,6 +828,7 @@ export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true
                 return "";
             }
         },
+        diagnosticCode: () => readKnownNpmDiagnosticCode(errPath),
         timeoutMarker: timeoutPath,
         errorMarker: errorPath,
         timedOut: () => existsSync(timeoutPath),
@@ -827,6 +870,7 @@ export function runSupervisedUpdateCommand(cmd, args, output, env) {
                 reapMs: UPDATE_REAP_GRACE_MS,
                 timeoutMarker: output.timeoutMarker,
                 errorMarker: output.errorMarker,
+                diagnosticMarker: output.diagnosticMarker,
             }),
         ], inOwnProcessGroup({
             stdio: output.stdio,
@@ -863,6 +907,8 @@ export function runSupervisedUpdateCommand(cmd, args, output, env) {
             const captured = output.stderrTail();
             return {
                 ok: false,
+                diagnosticCode: output.diagnosticCode(),
+                failureKind: "package_manager_exit",
                 detail: captured || `exit ${result.status ?? "signal"}`,
             };
         }
@@ -1214,6 +1260,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.
@@ -1250,8 +1297,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}`));
@@ -1267,7 +1326,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 && result.code !== "ETIMEDOUT" && prefix) {
+    if (!result.ok && result.code !== "ETIMEDOUT" && prefix && !stagedNpmPrefix) {
         const cleaner = deps.cleanStale ?? cleanStalePartialInstall;
         const cleaned = cleaner(prefix);
         if (cleaned.length > 0) {
@@ -1292,7 +1351,8 @@ function attemptRequiredUpdate(decision, deps, install) {
         !result.ok &&
         result.code !== "ETIMEDOUT" &&
         primaryCmd &&
-        !isManagedOutsideNpm) {
+        !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)
@@ -1358,9 +1418,16 @@ export async function enforceVersionGate(onUpdateRecommended, options = {}) {
     // 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 });
+        enforceUpdateRequired(decision, { resolveInstall: () => install, installNpmPackageStaged });
         return "continue";
     }
     if (decision.updateRecommended) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.300.0",
+  "version": "5.301.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -25,7 +25,7 @@
     "build": "node scripts/generate-dsn.mjs && node scripts/build-flag-registry-worker.mjs && tsc && node scripts/generate-command-catalog.mjs --check && node scripts/copy-schemas.mjs && node scripts/chmod-bins.mjs",
     "prepublishOnly": "npm run build",
     "pretypecheck": "node scripts/generate-dsn.mjs && node scripts/build-flag-registry-worker.mjs",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.typetest.json",
     "gen:scan-golden": "node scripts/generate-scan-packages-table.mjs > src/utils/__fixtures__/scan-packages.generated-block.sh",
     "gen:command-catalog": "tsc && node scripts/generate-command-catalog.mjs",
     "lint": "eslint .",

package/dist/lib/install-path-compatibility-flag.d.ts

@@ -1,9 +0,0 @@
-export declare const INSTALL_PATH_COMPATIBILITY_FLAG = "cli.install-path-compatibility";
-export declare const INSTALL_PATH_COMPATIBILITY_FALLBACK = false;
-/**
- * Read the default-off rollout flag from the process snapshot. Missing,
- * unreadable, or not-yet-loaded registry state keeps the compatibility fixes
- * disabled until the operator enables a canary.
- */
-export declare function installPathCompatibilityEnabled(): boolean;
-//# sourceMappingURL=install-path-compatibility-flag.d.ts.map

package/dist/lib/install-path-compatibility-flag.js

@@ -1,12 +0,0 @@
-import { resolveProcessFlagGate } from "./flag-registry.js";
-export const INSTALL_PATH_COMPATIBILITY_FLAG = "cli.install-path-compatibility";
-export const INSTALL_PATH_COMPATIBILITY_FALLBACK = false;
-/**
- * Read the default-off rollout flag from the process snapshot. Missing,
- * unreadable, or not-yet-loaded registry state keeps the compatibility fixes
- * disabled until the operator enables a canary.
- */
-export function installPathCompatibilityEnabled() {
-    return resolveProcessFlagGate(INSTALL_PATH_COMPATIBILITY_FLAG, {}, () => INSTALL_PATH_COMPATIBILITY_FALLBACK);
-}
-//# sourceMappingURL=install-path-compatibility-flag.js.map