@indigoai-us/hq-cli 5.115.5 → 5.116.0

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

@@ -0,0 +1,114 @@
+/**
+ * Install / uninstall / status for a SET of user-level services, dispatching
+ * to launchd or systemd. All filesystem and process-control effects are
+ * injectable so the kit tests exercise the real rendering and dispatch
+ * without touching the host's service manager.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import { activateLaunchd, deactivateLaunchd, launchAgentsDir, launchdIsLoaded, launchdPlistPath, renderLaunchdPlist, } from "./launchd.js";
+import { activateSystemd, deactivateSystemd, renderSystemdUserUnit, systemdIsActive, systemdUnitName, systemdUnitPath, systemdUserDir, } from "./systemd.js";
+import { detectServicePlatform, } from "./types.js";
+export { detectServicePlatform } from "./types.js";
+export { renderLaunchdPlist } from "./launchd.js";
+export { renderSystemdUserUnit, systemdUnitName } from "./systemd.js";
+export const defaultRunCommand = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8" });
+    return {
+        status: r.status,
+        stdout: r.stdout ?? "",
+        stderr: r.error ? r.error.message : (r.stderr ?? ""),
+    };
+};
+function unitPathFor(platform, home, spec) {
+    return platform === "darwin" ? launchdPlistPath(home, spec) : systemdUnitPath(home, spec);
+}
+export function renderUnit(platform, spec, host) {
+    return platform === "darwin"
+        ? renderLaunchdPlist(spec, host)
+        : renderSystemdUserUnit(spec, host);
+}
+export function installServices(specs, host, deps = {}) {
+    const platform = deps.platform ?? detectServicePlatform();
+    const run = deps.run ?? defaultRunCommand;
+    const writeFileSync = deps.writeFileSync ?? fs.writeFileSync;
+    const mkdirSync = deps.mkdirSync ?? fs.mkdirSync;
+    const activate = deps.activate ?? true;
+    if (platform === "other") {
+        return {
+            platform,
+            units: specs.map((s) => ({ name: s.name, unitPath: "", installed: false })),
+            manualCommands: specs.map((s) => `${host.nodeBinary} ${host.hqBinary} ${s.args.join(" ")}  # >> ${s.logPath}`),
+        };
+    }
+    const dir = platform === "darwin" ? launchAgentsDir(host.home) : systemdUserDir(host.home);
+    mkdirSync(dir, { recursive: true });
+    const units = [];
+    for (const spec of specs) {
+        const unitPath = unitPathFor(platform, host.home, spec);
+        const rendered = renderUnit(platform, spec, host);
+        writeFileSync(unitPath, rendered, { mode: 0o600 });
+        const unit = { name: spec.name, unitPath, rendered, installed: true };
+        if (activate) {
+            try {
+                if (platform === "darwin")
+                    activateLaunchd(unitPath, run);
+                else
+                    activateSystemd(systemdUnitName(spec), run);
+                unit.running = true;
+            }
+            catch (err) {
+                unit.running = false;
+                unit.error = err instanceof Error ? err.message : String(err);
+            }
+        }
+        units.push(unit);
+    }
+    return { platform, units };
+}
+export function uninstallServices(specs, host, deps = {}) {
+    const platform = deps.platform ?? detectServicePlatform();
+    const run = deps.run ?? defaultRunCommand;
+    const unlinkSync = deps.unlinkSync ?? fs.unlinkSync;
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    const activate = deps.activate ?? true;
+    if (platform === "other") {
+        return { platform, units: specs.map((s) => ({ name: s.name, unitPath: "", installed: false })) };
+    }
+    const units = [];
+    for (const spec of specs) {
+        const unitPath = unitPathFor(platform, host.home, spec);
+        const present = existsSync(unitPath);
+        if (present) {
+            if (activate) {
+                if (platform === "darwin")
+                    deactivateLaunchd(unitPath, run);
+                else
+                    deactivateSystemd(systemdUnitName(spec), run);
+            }
+            unlinkSync(unitPath);
+        }
+        units.push({ name: spec.name, unitPath, installed: false, running: false });
+    }
+    return { platform, units };
+}
+export function servicesStatus(specs, host, deps = {}) {
+    const platform = deps.platform ?? detectServicePlatform();
+    const run = deps.run ?? defaultRunCommand;
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    if (platform === "other") {
+        return { platform, units: specs.map((s) => ({ name: s.name, unitPath: "", installed: false })) };
+    }
+    const units = specs.map((spec) => {
+        const unitPath = unitPathFor(platform, host.home, spec);
+        const installed = existsSync(unitPath);
+        const running = installed
+            ? platform === "darwin"
+                ? launchdIsLoaded(spec.label, run)
+                : systemdIsActive(systemdUnitName(spec), run)
+            : false;
+        return { name: spec.name, unitPath, installed, running };
+    });
+    return { platform, units };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,23 @@
+/**
+ * macOS LaunchAgent rendering + activation for kit services.
+ *
+ * Units live at ~/Library/LaunchAgents/<label>.plist. Activation uses the
+ * modern `launchctl bootstrap gui/<uid>` form (bootout first so a re-install
+ * picks up a changed plist). Command execution is injected so tests never
+ * touch launchctl.
+ */
+import { type ServiceHostPaths, type ServiceSpec } from "./types.js";
+export declare const LAUNCHD_PATH_ENV = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
+export declare function launchAgentsDir(home: string): string;
+export declare function launchdPlistPath(home: string, spec: Pick<ServiceSpec, "label">): string;
+export declare function renderLaunchdPlist(spec: ServiceSpec, host: ServiceHostPaths): string;
+export type RunCommand = (cmd: string, args: string[]) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+/** (Re)load a plist: bootout is best-effort (not loaded yet is fine). */
+export declare function activateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
+export declare function deactivateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
+export declare function launchdIsLoaded(label: string, run: RunCommand, uid?: number): boolean;
+//# sourceMappingURL=launchd.d.ts.map

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

@@ -0,0 +1,81 @@
+/**
+ * macOS LaunchAgent rendering + activation for kit services.
+ *
+ * Units live at ~/Library/LaunchAgents/<label>.plist. Activation uses the
+ * modern `launchctl bootstrap gui/<uid>` form (bootout first so a re-install
+ * picks up a changed plist). Command execution is injected so tests never
+ * touch launchctl.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import { escapeXml, } from "./types.js";
+export const LAUNCHD_PATH_ENV = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
+export function launchAgentsDir(home) {
+    return path.join(home, "Library", "LaunchAgents");
+}
+export function launchdPlistPath(home, spec) {
+    return path.join(launchAgentsDir(home), `${spec.label}.plist`);
+}
+export function renderLaunchdPlist(spec, host) {
+    const args = [host.nodeBinary, host.hqBinary, ...spec.args]
+        .map((a) => `    <string>${escapeXml(a)}</string>`)
+        .join("\n");
+    const env = {
+        HOME: host.home,
+        PATH: LAUNCHD_PATH_ENV,
+        ...spec.env,
+    };
+    const envXml = Object.entries(env)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `    <key>${escapeXml(k)}</key>\n    <string>${escapeXml(v)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(spec.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(spec.workingDir)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>${spec.restartSec}</integer>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(spec.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(spec.logPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+</dict>
+</plist>
+`;
+}
+function guiDomain(uid = os.userInfo().uid) {
+    return `gui/${uid}`;
+}
+/** (Re)load a plist: bootout is best-effort (not loaded yet is fine). */
+export function activateLaunchd(plistPath, run, uid) {
+    const domain = guiDomain(uid);
+    run("launchctl", ["bootout", domain, plistPath]);
+    const r = run("launchctl", ["bootstrap", domain, plistPath]);
+    if (r.status !== 0) {
+        throw new Error(`launchctl bootstrap failed for ${plistPath}: ${r.stderr.trim() || r.stdout.trim() || `exit ${r.status}`}`);
+    }
+}
+export function deactivateLaunchd(plistPath, run, uid) {
+    run("launchctl", ["bootout", guiDomain(uid), plistPath]);
+}
+export function launchdIsLoaded(label, run, uid) {
+    const r = run("launchctl", ["print", `${guiDomain(uid)}/${label}`]);
+    return r.status === 0;
+}
+//# sourceMappingURL=launchd.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * 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 { type ServiceHostPaths, type ServiceSpec } from "./types.js";
+import type { RunCommand } from "./launchd.js";
+export declare const SYSTEMD_PATH_ENV = "/usr/local/bin:/usr/bin:/bin";
+export declare function systemdUserDir(home: string): string;
+export declare function systemdUnitName(spec: Pick<ServiceSpec, "name">): string;
+export declare function systemdUnitPath(home: string, spec: Pick<ServiceSpec, "name">): string;
+export declare function renderSystemdUserUnit(spec: ServiceSpec, host: ServiceHostPaths): string;
+export declare function activateSystemd(unitName: string, run: RunCommand): void;
+export declare function deactivateSystemd(unitName: string, run: RunCommand): void;
+export declare function systemdIsActive(unitName: string, run: RunCommand): boolean;
+//# sourceMappingURL=systemd.d.ts.map

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