@indigoai-us/hq-cli 5.115.6 → 5.117.0

package/dist/lib/service-manager/systemd.js

@@ -0,0 +1,72 @@
+/**
+ * Linux systemd USER unit rendering + activation for kit services.
+ *
+ * Units live at ~/.config/systemd/user/<name>.service and are enabled with
+ * `systemctl --user enable --now`. A host without a user session bus (some
+ * containers, headless boxes) cannot run user units; the kit's Docker image
+ * is the escape hatch there. Command execution is injected for tests.
+ */
+import * as path from "node:path";
+import { shellQuote, } from "./types.js";
+export const SYSTEMD_PATH_ENV = "/usr/local/bin:/usr/bin:/bin";
+export function systemdUserDir(home) {
+    return path.join(home, ".config", "systemd", "user");
+}
+export function systemdUnitName(spec) {
+    return `hq-agent-${spec.name}.service`;
+}
+export function systemdUnitPath(home, spec) {
+    return path.join(systemdUserDir(home), systemdUnitName(spec));
+}
+export function renderSystemdUserUnit(spec, host) {
+    const exec = [host.nodeBinary, host.hqBinary, ...spec.args].map(shellQuote).join(" ");
+    const env = {
+        HOME: host.home,
+        PATH: SYSTEMD_PATH_ENV,
+        ...spec.env,
+    };
+    const envLines = Object.entries(env)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `Environment=${shellQuote(`${k}=${v}`)}`)
+        .join("\n");
+    return `[Unit]
+Description=${spec.description}
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+WorkingDirectory=${spec.workingDir}
+Restart=always
+RestartSec=${spec.restartSec}
+${envLines}
+StandardOutput=append:${spec.logPath}
+StandardError=append:${spec.logPath}
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function activateSystemd(unitName, run) {
+    const reload = run("systemctl", ["--user", "daemon-reload"]);
+    if (reload.status !== 0) {
+        throw new Error(`systemctl --user daemon-reload failed: ${reload.stderr.trim() || `exit ${reload.status}`}. ` +
+            `No user session bus? Use the hq-agent-kit Docker image instead.`);
+    }
+    const r = run("systemctl", ["--user", "enable", "--now", unitName]);
+    if (r.status !== 0) {
+        throw new Error(`systemctl --user enable --now ${unitName} failed: ${r.stderr.trim() || `exit ${r.status}`}`);
+    }
+    // A re-install with a changed unit must restart the running instance.
+    run("systemctl", ["--user", "restart", unitName]);
+}
+export function deactivateSystemd(unitName, run) {
+    run("systemctl", ["--user", "disable", "--now", unitName]);
+    run("systemctl", ["--user", "daemon-reload"]);
+}
+export function systemdIsActive(unitName, run) {
+    const r = run("systemctl", ["--user", "is-active", "--quiet", unitName]);
+    return r.status === 0;
+}
+//# sourceMappingURL=systemd.js.map

package/dist/lib/service-manager/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Platform-neutral description of a user-level background service. The
+ * launchd and systemd renderers turn one of these into a unit; the kit
+ * installer owns the list. Every service is just `node hq <args…>` so the
+ * unit files carry no logic of their own.
+ */
+export interface ServiceSpec {
+    /** Short name — unit file stem and log file stem (`sync`, `mesh`, …). */
+    name: string;
+    /** Reverse-DNS launchd label; systemd derives its unit name from `name`. */
+    label: string;
+    description: string;
+    /** Arguments passed to the hq binary (after `node hq`). */
+    args: string[];
+    /** Absolute log path (stdout + stderr appended). */
+    logPath: string;
+    workingDir: string;
+    /** Extra environment for the unit (HOME/PATH are always set). */
+    env: Record<string, string>;
+    /** Seconds to wait before a restart after exit. */
+    restartSec: number;
+}
+export interface ServiceHostPaths {
+    home: string;
+    nodeBinary: string;
+    hqBinary: string;
+}
+export type ServicePlatform = "darwin" | "linux" | "other";
+export declare function detectServicePlatform(platform?: NodeJS.Platform): ServicePlatform;
+export declare function escapeXml(value: string): string;
+export declare function shellQuote(value: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/service-manager/types.js

@@ -0,0 +1,26 @@
+/**
+ * Platform-neutral description of a user-level background service. The
+ * launchd and systemd renderers turn one of these into a unit; the kit
+ * installer owns the list. Every service is just `node hq <args…>` so the
+ * unit files carry no logic of their own.
+ */
+export function detectServicePlatform(platform = process.platform) {
+    if (platform === "darwin")
+        return "darwin";
+    if (platform === "linux")
+        return "linux";
+    return "other";
+}
+export function escapeXml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+export function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:=-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+//# sourceMappingURL=types.js.map

package/dist/utils/self-update.js

@@ -60,7 +60,7 @@ import { spawnSync } from "node:child_process";
 import semver from "semver";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
-import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, checkUpdateConvergence, inOwnProcessGroup, isLocalDependencyInstall, isPrefixWritable, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, checkUpdateConvergence, isLocalDependencyInstall, isPrefixWritable, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, } from "./version-gate.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
 /**
@@ -70,8 +70,6 @@ import { markLatestIneffective } from "./version-check.js";
 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;
-/** 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). */
 async function fetchLatestVersion() {
     try {
@@ -115,33 +113,7 @@ export function runUpdateQuiet(cmd, args, env) {
     // the installer down with it mid-write. See `openInstallOutput`.
     const output = openInstallOutput(false);
     try {
-        const plan = buildSpawnPlan(cmd, args);
-        // `inOwnProcessGroup`: the install must survive a signal aimed at this
-        // process, or a killed `hq` leaves a corrupted global install behind.
-        const result = spawnSync(plan.cmd, plan.args, inOwnProcessGroup({
-            stdio: output.stdio,
-            shell: plan.shell,
-            ...(env ? { env } : {}),
-        }));
-        if (result.error) {
-            const code = result.error.code;
-            return { ok: false, code, detail: result.error.message };
-        }
-        if (result.status !== 0) {
-            const tail = output.stderrTail().slice(-DETAIL_MAX_CHARS);
-            return {
-                ok: false,
-                detail: tail || `exit ${result.status ?? "signal"}`,
-            };
-        }
-        return { ok: true };
-    }
-    catch (err) {
-        return {
-            ok: false,
-            code: err?.code,
-            detail: err instanceof Error ? err.message : String(err),
-        };
+        return runSupervisedUpdateCommand(cmd, args, output, env);
     }
     finally {
         output.dispose();

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

@@ -0,0 +1,194 @@
+"use strict";
+
+const { spawn: nativeSpawn } = require("node:child_process");
+const fs = require("node:fs");
+
+function windowsTaskkillArgs(pid) {
+  return ["/PID", String(pid), "/T", "/F"];
+}
+
+function errorInfo(error) {
+  return {
+    code: error && typeof error.code === "string" ? error.code : undefined,
+    detail:
+      error && typeof error.message === "string" ? error.message : String(error ?? "unknown error"),
+  };
+}
+
+function writeMarker(filename, contents, log) {
+  try {
+    fs.writeFileSync(filename, contents);
+  } catch (error) {
+    const { detail } = errorInfo(error);
+    log(`[hq update supervisor] failed to record updater status: ${detail}`);
+  }
+}
+
+/**
+ * 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
+ * descendant. Windows command shims run below a shell, therefore taskkill is
+ * used there to terminate the full descendant tree instead of only that shell.
+ *
+ * Dependencies are injectable to pin failure handling without requiring root
+ * privileges or a Windows host in the test suite.
+ */
+function runUpdateSupervisor(config, dependencies = {}) {
+  const spawn = dependencies.spawn || nativeSpawn;
+  const signal = dependencies.kill || process.kill.bind(process);
+  const setTimer = dependencies.setTimeout || setTimeout;
+  const clearTimer = dependencies.clearTimeout || clearTimeout;
+  const platform = dependencies.platform || process.platform;
+  const exit = dependencies.exit || ((code) => process.exit(code));
+  const log = dependencies.log || console.error;
+
+  let child;
+  let deadlineTimer;
+  let graceTimer;
+  let reapTimer;
+  let finished = false;
+  let timedOut = false;
+  let childClosed = false;
+  let treeTerminationConfirmed = false;
+
+  function clear(timer) {
+    if (timer !== undefined) clearTimer(timer);
+  }
+
+  function finish(code, options = {}) {
+    if (finished) return;
+    finished = true;
+    clear(deadlineTimer);
+    clear(graceTimer);
+    clear(reapTimer);
+    if (options.timedOut) writeMarker(config.timeoutMarker, "timed-out", log);
+    if (options.error) writeMarker(config.errorMarker, JSON.stringify(options.error), log);
+    exit(code);
+  }
+
+  function timeoutFailure(code, detail) {
+    finish(124, {
+      timedOut: true,
+      error: { code, detail },
+    });
+  }
+
+  function timeoutAfterReap() {
+    finish(124, { timedOut: true });
+  }
+
+  function waitForReap(after) {
+    if (childClosed) {
+      timeoutAfterReap();
+      return;
+    }
+    reapTimer = setTimer(() => {
+      timeoutFailure(
+        "EREAP",
+        `timed out after ${config.timeoutMs}ms and ${after} did not close the updater process`,
+      );
+    }, config.reapMs);
+  }
+
+  function signalProcessGroup(signalName) {
+    if (!child || !child.pid) {
+      timeoutFailure("ESRCH", `failed to send ${signalName}: updater has no process ID`);
+      return "failed";
+    }
+    try {
+      signal(-child.pid, signalName);
+      return "sent";
+    } catch (error) {
+      const { code, detail } = errorInfo(error);
+      if (code === "ESRCH") return "gone";
+      // An EPERM here is possible after the sudo retry: waiting would violate
+      // the deadline, while claiming the process tree was reaped would lie.
+      timeoutFailure(code, `failed to send ${signalName} to updater process group: ${detail}`);
+      return "failed";
+    }
+  }
+
+  function terminateWindowsTree() {
+    if (!child || !child.pid) {
+      timeoutFailure("ESRCH", "failed to start taskkill: updater has no process ID");
+      return;
+    }
+    let killer;
+    try {
+      killer = spawn("taskkill", windowsTaskkillArgs(child.pid), {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } catch (error) {
+      const { code, detail } = errorInfo(error);
+      timeoutFailure(code, `failed to start taskkill for updater process tree: ${detail}`);
+      return;
+    }
+    killer.once("error", (error) => {
+      const { code, detail } = errorInfo(error);
+      timeoutFailure(code, `taskkill failed for updater process tree: ${detail}`);
+    });
+    killer.once("close", (code) => {
+      if (code !== 0) {
+        timeoutFailure("ETASKKILL", `taskkill exited ${code ?? "without a status"} for updater process tree`);
+        return;
+      }
+      treeTerminationConfirmed = true;
+      waitForReap("taskkill");
+    });
+  }
+
+  try {
+    child = spawn(config.cmd, config.args, {
+      detached: true,
+      stdio: ["ignore", "inherit", "inherit"],
+      shell: config.shell,
+    });
+  } catch (error) {
+    const { code, detail } = errorInfo(error);
+    finish(127, { error: { code, detail } });
+    return;
+  }
+
+  child.once("error", (error) => {
+    const { code, detail } = errorInfo(error);
+    finish(127, { error: { code, detail } });
+  });
+  child.once("close", (code) => {
+    childClosed = true;
+    if (!timedOut) {
+      finish(code === 0 ? 0 : (code ?? 1));
+      return;
+    }
+    if (treeTerminationConfirmed) timeoutAfterReap();
+  });
+
+  deadlineTimer = setTimer(() => {
+    if (finished) return;
+    timedOut = true;
+    if (platform === "win32") {
+      terminateWindowsTree();
+      return;
+    }
+    const term = signalProcessGroup("SIGTERM");
+    if (term === "failed") return;
+    if (term === "gone") {
+      treeTerminationConfirmed = true;
+      waitForReap("the already-exited process group");
+      return;
+    }
+    graceTimer = setTimer(() => {
+      if (finished) return;
+      const kill = signalProcessGroup("SIGKILL");
+      if (kill === "failed") return;
+      treeTerminationConfirmed = true;
+      waitForReap(kill === "gone" ? "the already-exited process group" : "SIGKILL");
+    }, config.graceMs);
+  }, config.timeoutMs);
+}
+
+if (require.main === module) {
+  runUpdateSupervisor(JSON.parse(process.argv[2]));
+}
+
+module.exports = { runUpdateSupervisor, windowsTaskkillArgs };

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

@@ -283,6 +283,7 @@ export { buildSpawnPlan, quoteForWindowsShell };
  * protection silently disappearing.
  */
 export declare function inOwnProcessGroup<T extends object>(options: T): T;
+declare function updateTimeoutMs(env?: NodeJS.ProcessEnv): number;
 /**
  * Where an install's output goes — the other half of surviving a killed parent.
  *
@@ -307,9 +308,21 @@ export interface InstallOutput {
     stdio: ("ignore" | "inherit" | number)[];
     /** Captured stderr tail, or "" when output was inherited by a terminal. */
     stderrTail: () => 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. */
+    errorMarker: string;
+    /** Whether the asynchronous installer supervisor reported a deadline expiry. */
+    timedOut: () => boolean;
+    /** Original package-manager launch error, if the supervisor could start. */
+    spawnError: () => {
+        code?: string;
+        detail?: string;
+    } | undefined;
     dispose: () => void;
 }
 export declare function openInstallOutput(verbose: boolean, isTty?: boolean): InstallOutput;
+export declare function runSupervisedUpdateCommand(cmd: string, args: string[], output: InstallOutput, env?: NodeJS.ProcessEnv): UpdateResult;
 export declare function runUpdateCommand(cmd: string, args: string[], env?: NodeJS.ProcessEnv): UpdateResult;
 declare function performUpdateCommand(cmd: string, args: string[], runner?: UpdateRunner, env?: NodeJS.ProcessEnv): UpdateResult;
 declare function performUpdate(command: string, runner?: UpdateRunner): UpdateResult;
@@ -385,6 +398,9 @@ interface EnforceUpdateDeps {
  * 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.
  */
 declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: EnforceUpdateDeps): void;
 /**
@@ -418,6 +434,7 @@ export declare function shouldSkipGate(argv: readonly string[]): boolean;
 export declare const __test__: {
     CLIENT_ID: string;
     CONVERGENCE_TIMEOUT_MS: number;
+    DEFAULT_UPDATE_TIMEOUT_MS: number;
     ENDPOINT_PATH: string;
     FETCH_TIMEOUT_MS: number;
     checkUpdateConvergence: typeof checkUpdateConvergence;
@@ -448,5 +465,6 @@ export declare const __test__: {
     resolveRunningInstall: typeof resolveRunningInstall;
     resolveRunningManager: typeof resolveRunningManager;
     resolveRunningPrefix: typeof resolveRunningPrefix;
+    updateTimeoutMs: typeof updateTimeoutMs;
 };
 //# sourceMappingURL=version-gate.d.ts.map

package/dist/utils/version-gate.js

@@ -534,16 +534,74 @@ export function inOwnProcessGroup(options) {
 }
 /** Tail of captured installer stderr kept to explain a failure. */
 const INSTALL_DETAIL_MAX_CHARS = 400;
+/** 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));
+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");
         return {
             stdio: ["ignore", "inherit", "inherit"],
             stderrTail: () => "",
-            dispose: () => { },
+            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 +614,10 @@ export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true
                 return "";
             }
         },
+        timeoutMarker: timeoutPath,
+        errorMarker: errorPath,
+        timedOut: () => existsSync(timeoutPath),
+        spawnError: () => readSupervisorSpawnError(errorPath),
         dispose: () => {
             for (const fd of [out, err]) {
                 try {
@@ -574,13 +636,28 @@ 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, [
+            UPDATE_COMMAND_SUPERVISOR,
+            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,
+            }),
+        ], inOwnProcessGroup({
             stdio: output.stdio,
-            shell: plan.shell,
             ...(env ? { env } : {}),
         }));
         // spawnSync reports a missing executable via `error`, not a throw.
@@ -588,6 +665,26 @@ 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.
@@ -606,6 +703,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();
     }
@@ -796,6 +899,9 @@ 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}).`);
@@ -858,6 +964,8 @@ function enforceUpdateRequired(decision, deps = {}) {
         // unexpected throw from the install attempt.
         lock.release();
     }
+    if (exitCode === "continue")
+        return;
     process.exit(exitCode);
 }
 /**
@@ -923,7 +1031,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) {
         const cleaner = deps.cleanStale ?? cleanStalePartialInstall;
         const cleaned = cleaner(prefix);
         if (cleaned.length > 0) {
@@ -943,7 +1051,7 @@ 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) {
+    if (!result.ok && result.code !== "ETIMEDOUT" && primaryCmd && !isManagedOutsideNpm) {
         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)
@@ -973,6 +1081,15 @@ 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.)`));
         }
+        // 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 75;
     }
     // Read-your-writes: a "successful" install into the npm prefix does not
@@ -1028,6 +1145,7 @@ export function shouldSkipGate(argv) {
 export const __test__ = {
     CLIENT_ID,
     CONVERGENCE_TIMEOUT_MS,
+    DEFAULT_UPDATE_TIMEOUT_MS,
     ENDPOINT_PATH,
     FETCH_TIMEOUT_MS,
     checkUpdateConvergence,
@@ -1058,5 +1176,6 @@ export const __test__ = {
     resolveRunningInstall,
     resolveRunningManager,
     resolveRunningPrefix,
+    updateTimeoutMs,
 };
 //# sourceMappingURL=version-gate.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.115.6",
+  "version": "5.117.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -34,7 +34,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.16.41",
+    "@indigoai-us/hq-cloud": "~6.16.48",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",