@indigoai-us/hq-cli 5.101.7 → 5.103.0

package/dist/lib/doctor/checks/runtime-health.d.ts

@@ -0,0 +1,100 @@
+/**
+ * AI runtime health: are the CLIs HQ orchestrates actually able to answer?
+ *
+ * Every hooks-family check verifies HQ's own wiring. This family verifies the
+ * other half of the contract: the Claude, Codex, and Grok CLIs themselves. A
+ * tree can pass every wiring check while `codex` is logged out, `grok` is not
+ * installed, or `claude` is broken by a bad update — and until this family
+ * existed `hq doctor` would still report all green.
+ *
+ * ## Two tiers, mirroring the doctor's offline contract
+ *
+ *   1. **Presence (always).** Resolving each binary against PATH is a pure
+ *      filesystem scan — no process is spawned — so a plain `hq doctor` stays a
+ *      function of the on-disk shape. A missing binary is WARN, not FAIL: HQ
+ *      wires hooks for all three runtimes, but not every machine runs all three.
+ *
+ *   2. **Live probes (`--live-runtimes` only).** Reads the CLI's version and
+ *      sends it a one-line prompt, verifying the full path: binary → auth →
+ *      subscription → model → response. This is the doctor's ONLY networked
+ *      tier and it never runs without the flag; without it the live checks
+ *      report UNTESTED, never PASS — installed is not the same as working.
+ *
+ * Probes run from the OS temp directory, never the HQ tree, so a probe cannot
+ * trigger HQ's own hook stack or leave session state behind, and each one is
+ * bounded by a timeout. A timeout or spawn error is UNKNOWN (could not be
+ * determined), while a clean non-zero exit — the logged-out case — is FAIL.
+ */
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+/** The id of the AI-runtime-health family. */
+export declare const RUNTIMES_FAMILY_ID = "runtimes";
+/** Common id prefix for every result this family emits. */
+export declare const RUNTIMES_PREFIX = "runtimes";
+/**
+ * The deterministic one-line probe prompt. Health is proven by a round-trip
+ * (exit 0 plus non-empty output), not by exact-matching the reply, so a model
+ * that answers with anything at all still passes.
+ */
+export declare const PROBE_PROMPT = "Reply with exactly: OK";
+/** How long each live probe may run before it is killed and marked UNKNOWN. */
+export declare const DEFAULT_PROBE_TIMEOUT_MS = 120000;
+/** One AI runtime the doctor knows how to find and probe. */
+export interface RuntimeSpec {
+    /** Stable key used in check ids, e.g. `runtimes.codex.binary`. */
+    key: string;
+    /** Human display name for messages. */
+    displayName: string;
+    /** The executable name resolved against PATH. */
+    binary: string;
+    /** Arguments that print the version and exit (offline, auth-free). */
+    versionArgs: string[];
+    /** Arguments for the non-interactive one-line prompt probe. */
+    probeArgs: string[];
+    /** Remediation hint when the binary is not on PATH. */
+    installHint: string;
+}
+/**
+ * The three runtimes HQ wires hooks for. Codex runs its probe under its own
+ * read-only sandbox and outside-a-repo mode so the probe can never write; the
+ * Claude and Grok print modes are non-interactive and make no edits.
+ */
+export declare const AI_RUNTIMES: readonly RuntimeSpec[];
+/** The outcome of one spawned probe, normalised so callers never throw. */
+export interface ProbeOutcome {
+    /** True iff the process spawned and exited 0. */
+    ok: boolean;
+    /** Exit code, or null when the process never exited normally. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    /** True when the probe was killed by the timeout. */
+    timedOut: boolean;
+    /** Present when the spawn itself failed (ENOENT, EACCES, …). */
+    spawnError?: string;
+}
+/** Injectable dependencies so the family is unit-testable without spawning. */
+export interface RuntimeHealthDeps {
+    /** Resolve an executable against PATH; null when not found. */
+    resolveBinary?: (binary: string) => string | null;
+    /** Execute one probe. The default spawns from the OS temp dir. */
+    execProbe?: (file: string, args: string[], timeoutMs: number) => Promise<ProbeOutcome>;
+    /** Per-probe timeout. Default {@link DEFAULT_PROBE_TIMEOUT_MS}. */
+    probeTimeoutMs?: number;
+}
+/**
+ * The AI-runtime-health check family entry. Presence checks always run; the
+ * version and prompt probes run only when the context carries `liveRuntimes`
+ * (the `--live-runtimes` flag). Never rejects — an unexpected throw degrades
+ * to a single UNKNOWN result, mirroring the hooks family's safeTier.
+ */
+export declare function checkRuntimeHealth(context: CheckContext, deps?: RuntimeHealthDeps): Promise<CheckResult[]>;
+/** The registered family object. */
+export declare const runtimeHealthFamily: CheckFamily;
+/**
+ * Resolve an executable name against PATH with a pure filesystem scan — no
+ * process is spawned, keeping the doctor's default run a function of on-disk
+ * shape. First PATH entry containing an executable regular file wins, which is
+ * exactly the copy a shell would run.
+ */
+export declare function resolveOnPath(binary: string): string | null;
+//# sourceMappingURL=runtime-health.d.ts.map

package/dist/lib/doctor/checks/runtime-health.js

@@ -0,0 +1,336 @@
+/**
+ * AI runtime health: are the CLIs HQ orchestrates actually able to answer?
+ *
+ * Every hooks-family check verifies HQ's own wiring. This family verifies the
+ * other half of the contract: the Claude, Codex, and Grok CLIs themselves. A
+ * tree can pass every wiring check while `codex` is logged out, `grok` is not
+ * installed, or `claude` is broken by a bad update — and until this family
+ * existed `hq doctor` would still report all green.
+ *
+ * ## Two tiers, mirroring the doctor's offline contract
+ *
+ *   1. **Presence (always).** Resolving each binary against PATH is a pure
+ *      filesystem scan — no process is spawned — so a plain `hq doctor` stays a
+ *      function of the on-disk shape. A missing binary is WARN, not FAIL: HQ
+ *      wires hooks for all three runtimes, but not every machine runs all three.
+ *
+ *   2. **Live probes (`--live-runtimes` only).** Reads the CLI's version and
+ *      sends it a one-line prompt, verifying the full path: binary → auth →
+ *      subscription → model → response. This is the doctor's ONLY networked
+ *      tier and it never runs without the flag; without it the live checks
+ *      report UNTESTED, never PASS — installed is not the same as working.
+ *
+ * Probes run from the OS temp directory, never the HQ tree, so a probe cannot
+ * trigger HQ's own hook stack or leave session state behind, and each one is
+ * bounded by a timeout. A timeout or spawn error is UNKNOWN (could not be
+ * determined), while a clean non-zero exit — the logged-out case — is FAIL.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** The id of the AI-runtime-health family. */
+export const RUNTIMES_FAMILY_ID = "runtimes";
+/** Common id prefix for every result this family emits. */
+export const RUNTIMES_PREFIX = "runtimes";
+/**
+ * The deterministic one-line probe prompt. Health is proven by a round-trip
+ * (exit 0 plus non-empty output), not by exact-matching the reply, so a model
+ * that answers with anything at all still passes.
+ */
+export const PROBE_PROMPT = "Reply with exactly: OK";
+/** How long each live probe may run before it is killed and marked UNKNOWN. */
+export const DEFAULT_PROBE_TIMEOUT_MS = 120_000;
+/**
+ * The three runtimes HQ wires hooks for. Codex runs its probe under its own
+ * read-only sandbox and outside-a-repo mode so the probe can never write; the
+ * Claude and Grok print modes are non-interactive and make no edits.
+ */
+export const AI_RUNTIMES = [
+    {
+        key: "claude",
+        displayName: "Claude Code",
+        binary: "claude",
+        versionArgs: ["--version"],
+        probeArgs: ["-p", PROBE_PROMPT],
+        installHint: "npm install -g @anthropic-ai/claude-code",
+    },
+    {
+        key: "codex",
+        displayName: "Codex CLI",
+        binary: "codex",
+        versionArgs: ["--version"],
+        probeArgs: [
+            "exec",
+            "--skip-git-repo-check",
+            "--sandbox",
+            "read-only",
+            PROBE_PROMPT,
+        ],
+        installHint: "npm install -g @openai/codex",
+    },
+    {
+        key: "grok",
+        displayName: "Grok CLI",
+        binary: "grok",
+        versionArgs: ["--version"],
+        probeArgs: ["-p", PROBE_PROMPT],
+        installHint: "install the Grok CLI and ensure `grok` is on PATH",
+    },
+];
+/**
+ * The AI-runtime-health check family entry. Presence checks always run; the
+ * version and prompt probes run only when the context carries `liveRuntimes`
+ * (the `--live-runtimes` flag). Never rejects — an unexpected throw degrades
+ * to a single UNKNOWN result, mirroring the hooks family's safeTier.
+ */
+export async function checkRuntimeHealth(context, deps = {}) {
+    try {
+        return await runRuntimeChecks(context, deps);
+    }
+    catch (error) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: `${RUNTIMES_PREFIX}.error`,
+                message: `AI runtime checks could not run: ${error.message}`,
+            },
+        ];
+    }
+}
+async function runRuntimeChecks(context, deps) {
+    const resolved = {
+        resolveBinary: deps.resolveBinary ?? resolveOnPath,
+        execProbe: deps.execProbe ?? defaultExecProbe,
+        timeoutMs: deps.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,
+        live: context.liveRuntimes === true,
+    };
+    // Each runtime's checks are independent, so probe them concurrently: total
+    // wall time is the slowest single runtime, not the sum of all three.
+    const perRuntime = await Promise.all(AI_RUNTIMES.map((spec) => checkOneRuntime(spec, resolved)));
+    return perRuntime.flat();
+}
+async function checkOneRuntime(spec, deps) {
+    const idBase = `${RUNTIMES_PREFIX}.${spec.key}`;
+    const resolvedPath = deps.resolveBinary(spec.binary);
+    if (!resolvedPath) {
+        return [
+            {
+                status: "WARN",
+                checkId: `${idBase}.binary`,
+                target: spec.binary,
+                message: `${spec.displayName} (\`${spec.binary}\`) was not found on PATH; HQ's ${spec.displayName} hook wiring can never fire on this machine.`,
+                remediation: `If you use ${spec.displayName} here: ${spec.installHint}.`,
+            },
+            {
+                status: "NA",
+                checkId: `${idBase}.responds`,
+                target: spec.binary,
+                message: `${spec.displayName} cannot be probed — the binary is not installed.`,
+            },
+        ];
+    }
+    const results = [
+        {
+            status: "PASS",
+            checkId: `${idBase}.binary`,
+            target: resolvedPath,
+            message: `${spec.displayName} (\`${spec.binary}\`) is on PATH at ${resolvedPath}.`,
+        },
+    ];
+    if (!deps.live) {
+        results.push({
+            status: "UNTESTED",
+            checkId: `${idBase}.responds`,
+            target: spec.binary,
+            message: `${spec.displayName} is installed but has not been exercised — installed is not the same as logged in and answering.`,
+            remediation: "Run `hq doctor --live-runtimes` to send each installed AI CLI a one-line prompt (networked; uses your subscriptions).",
+        });
+        return results;
+    }
+    // Live tier: version first (offline, auth-free), then the real prompt. The
+    // two run concurrently — they are independent evidence, and a broken CLI
+    // fails both cheaply.
+    const [version, probe] = await Promise.all([
+        deps.execProbe(resolvedPath, spec.versionArgs, deps.timeoutMs),
+        deps.execProbe(resolvedPath, spec.probeArgs, deps.timeoutMs),
+    ]);
+    results.push(versionResult(spec, idBase, version));
+    results.push(probeResult(spec, idBase, probe, deps.timeoutMs));
+    return results;
+}
+function versionResult(spec, idBase, outcome) {
+    const checkId = `${idBase}.version`;
+    if (outcome.ok) {
+        return {
+            status: "PASS",
+            checkId,
+            target: spec.binary,
+            message: `${spec.displayName} reports version: ${excerpt(outcome.stdout) || "(no output)"}.`,
+        };
+    }
+    if (outcome.timedOut || outcome.spawnError) {
+        return {
+            status: "UNKNOWN",
+            checkId,
+            target: spec.binary,
+            message: `${spec.displayName} version could not be read: ${outcome.timedOut ? "the command timed out" : outcome.spawnError}.`,
+        };
+    }
+    return {
+        status: "FAIL",
+        checkId,
+        target: spec.binary,
+        message: `\`${spec.binary} ${spec.versionArgs.join(" ")}\` exited ${outcome.code}: ${excerpt(outcome.stderr) || "(no stderr)"}.`,
+    };
+}
+function probeResult(spec, idBase, outcome, timeoutMs) {
+    const checkId = `${idBase}.responds`;
+    if (outcome.ok && outcome.stdout.trim().length > 0) {
+        return {
+            status: "PASS",
+            checkId,
+            target: spec.binary,
+            message: `${spec.displayName} answered a live prompt: "${excerpt(outcome.stdout)}".`,
+        };
+    }
+    if (outcome.timedOut) {
+        return {
+            status: "UNKNOWN",
+            checkId,
+            target: spec.binary,
+            message: `${spec.displayName} did not answer within ${Math.round(timeoutMs / 1000)}s — it may be hung, waiting on interactive input, or on a very slow network.`,
+            remediation: `Run \`${spec.binary}\` interactively to see what it is waiting on.`,
+        };
+    }
+    if (outcome.spawnError) {
+        return {
+            status: "UNKNOWN",
+            checkId,
+            target: spec.binary,
+            message: `${spec.displayName} could not be executed: ${outcome.spawnError}.`,
+        };
+    }
+    if (outcome.ok) {
+        return {
+            status: "FAIL",
+            checkId,
+            target: spec.binary,
+            message: `${spec.displayName} exited 0 but produced no output for the probe prompt — the runtime is not returning responses.`,
+            remediation: `Run \`${spec.binary}\` interactively to check login and subscription state.`,
+        };
+    }
+    return {
+        status: "FAIL",
+        checkId,
+        target: spec.binary,
+        message: `${spec.displayName} could not answer a live prompt (exit ${outcome.code}): ${excerpt(outcome.stderr) || excerpt(outcome.stdout) || "(no output)"}.`,
+        remediation: `Run \`${spec.binary}\` interactively to check login and subscription state.`,
+    };
+}
+/** The registered family object. */
+export const runtimeHealthFamily = {
+    id: RUNTIMES_FAMILY_ID,
+    title: "AI runtime health",
+    run: (context) => checkRuntimeHealth(context),
+};
+// --- default dependencies ----------------------------------------------------
+/**
+ * Resolve an executable name against PATH with a pure filesystem scan — no
+ * process is spawned, keeping the doctor's default run a function of on-disk
+ * shape. First PATH entry containing an executable regular file wins, which is
+ * exactly the copy a shell would run.
+ */
+export function resolveOnPath(binary) {
+    const pathVar = process.env.PATH ?? "";
+    for (const dir of pathVar.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, binary);
+        try {
+            if (!fs.statSync(candidate).isFile())
+                continue;
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Spawn one probe from the OS temp directory (never the HQ tree, so a probe
+ * cannot trigger HQ's hook stack or leave session state), bounded by the
+ * timeout. Never rejects — every failure mode is folded into the outcome.
+ *
+ * stdin is `ignore` (closed at /dev/null), not a pipe: `codex exec` — and any
+ * CLI that reads piped stdin in non-TTY mode — blocks forever on a pipe that
+ * never reaches EOF, which turns every probe into a timeout.
+ */
+function defaultExecProbe(file, args, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn(file, args, {
+            cwd: os.tmpdir(),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const cap = 1024 * 1024;
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let settled = false;
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            if (stdout.length < cap)
+                stdout += chunk;
+        });
+        child.stderr?.on("data", (chunk) => {
+            if (stderr.length < cap)
+                stderr += chunk;
+        });
+        // SIGTERM at the deadline, escalating to SIGKILL for a child that ignores
+        // it — a hung probe must never hang the doctor itself.
+        const killTimer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!settled)
+                    child.kill("SIGKILL");
+            }, 10_000).unref();
+        }, timeoutMs);
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(killTimer);
+            resolve(outcome);
+        };
+        child.on("error", (error) => settle({
+            ok: false,
+            code: null,
+            stdout,
+            stderr,
+            timedOut: false,
+            spawnError: error.message,
+        }));
+        child.on("close", (code) => settle({
+            ok: code === 0 && !timedOut,
+            code,
+            stdout,
+            stderr,
+            timedOut,
+        }));
+    });
+}
+/** Last non-empty line of output, whitespace-collapsed and capped for display. */
+function excerpt(output) {
+    const line = output
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .at(-1) ?? "";
+    const collapsed = line.replace(/\s+/g, " ");
+    return collapsed.length > 120 ? `${collapsed.slice(0, 117)}...` : collapsed;
+}
+//# sourceMappingURL=runtime-health.js.map

package/dist/lib/doctor/registry.js

@@ -18,6 +18,7 @@ import * as path from "node:path";
 import { checkCodexWiring } from "./checks/codex-wiring.js";
 import { checkGrokWiring } from "./checks/grok-wiring.js";
 import { checkRuntimeProbe } from "./checks/runtime-probe.js";
+import { runtimeHealthFamily } from "./checks/runtime-health.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -171,6 +172,11 @@ export function createDefaultRegistry() {
     // it needs no change to the hooks tier, per the registry's extensibility
     // contract.
     registry.register(fixtureCoverageFamily);
+    // AI runtime health: are the Claude / Codex / Grok CLIs installed and (with
+    // --live-runtimes) actually answering? Hooks wiring can be perfect while a
+    // runtime is logged out or broken; this family closes that blind spot. Its
+    // default tier is a pure PATH scan, preserving the offline contract.
+    registry.register(runtimeHealthFamily);
     return registry;
 }
 //# sourceMappingURL=registry.js.map

package/dist/lib/doctor/types.d.ts

@@ -59,6 +59,13 @@ export interface CheckContext {
      * Absent means "any session's ledger counts".
      */
     sessionId?: string;
+    /**
+     * When true, the AI-runtime-health family may execute live, networked probes
+     * of the installed AI CLIs (the `--live-runtimes` flag). Absent or false
+     * keeps the run offline: the live checks report UNTESTED instead of
+     * executing anything.
+     */
+    liveRuntimes?: boolean;
 }
 /**
  * A check family: an id, a human title, and an async `run` returning per-item

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

@@ -71,7 +71,7 @@ export declare function buildSelfUpdatePlan(install: RunningInstall): {
  * to stdout. Progress is summarised on stderr by the caller instead; captured
  * stderr is kept only to explain a failure.
  */
-export declare function runUpdateQuiet(cmd: string, args: string[]): UpdateResult;
+export declare function runUpdateQuiet(cmd: string, args: string[], env?: NodeJS.ProcessEnv): UpdateResult;
 /**
  * Serialize self-updates across concurrent `hq` processes. Without this, a
  * machine running several HQ agents can fire many `npm install -g` at the same
@@ -90,7 +90,7 @@ export interface SelfUpdateDeps {
     currentVersion?: string;
     fetchLatest?: () => Promise<string | null>;
     resolveInstall?: () => RunningInstall;
-    runner?: (cmd: string, args: string[]) => UpdateResult;
+    runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
     reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
     acquireLock?: () => (() => void) | null;
 }

package/dist/utils/self-update.js

@@ -38,7 +38,7 @@ import * as path from "node:path";
 import semver from "semver";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
-import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
  * One update + one re-exec per user invocation, ever.
@@ -88,13 +88,14 @@ export function buildSelfUpdatePlan(install) {
  * to stdout. Progress is summarised on stderr by the caller instead; captured
  * stderr is kept only to explain a failure.
  */
-export function runUpdateQuiet(cmd, args) {
+export function runUpdateQuiet(cmd, args, env) {
     try {
         const plan = buildSpawnPlan(cmd, args);
         const result = spawnSync(plan.cmd, plan.args, {
             stdio: ["ignore", "pipe", "pipe"],
             shell: plan.shell,
             encoding: "utf-8",
+            ...(env ? { env } : {}),
         });
         if (result.error) {
             const code = result.error.code;
@@ -200,10 +201,25 @@ async function updateAndReexec(argv, flavor, known, deps) {
     let result;
     const install = (deps.resolveInstall ?? resolveRunningInstall)();
     const plan = buildSelfUpdatePlan(install);
+    // A pnpm global install needs PNPM_HOME to find its global bin dir. A
+    // minimal-environment parent (systemd, cron, non-login shell) lacks it and
+    // `pnpm add -g` aborts with ERR_PNPM_NO_GLOBAL_BIN_DIR (exit 1), so the
+    // self-update never lands until the box is next touched from an interactive
+    // shell. Derive PNPM_HOME from the running install so the update works
+    // regardless of the parent environment. No-op for npm/bun and when the
+    // parent already sets PNPM_HOME.
+    const updateEnv = pnpmUpdateEnv(install, env);
     try {
         console.error(chalk.dim(`Updating hq-cli ${current} → ${latest}…`));
         const defaultRunner = flavor.verbose ? runUpdateCommand : runUpdateQuiet;
-        result = (deps.runner ?? defaultRunner)(plan.cmd, plan.args);
+        const runner = deps.runner ?? defaultRunner;
+        // Forward env only when PNPM_HOME had to be injected, so the common path
+        // spawns with the inherited environment and keeps the two-argument runner
+        // call it has always made.
+        result =
+            updateEnv === undefined
+                ? runner(plan.cmd, plan.args)
+                : runner(plan.cmd, plan.args, updateEnv);
     }
     finally {
         releaseLock();

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

@@ -96,6 +96,35 @@ export declare function resolveRunningInstall(): RunningInstall;
 export declare function resolveRunningManager(): InstallManager;
 /** Convenience view of {@link resolveRunningInstall} for callers needing one field. */
 export declare function resolveRunningPrefix(): string | null;
+/**
+ * Derive `PNPM_HOME` from a pnpm-managed install's own path. pnpm resolves its
+ * global bin directory from `PNPM_HOME` (or an explicit `global-bin-dir`), and
+ * `PNPM_HOME` is the path segment immediately preceding pnpm's global root, e.g.
+ *
+ *   /home/u/.local/share/pnpm/global/5/…  ->  PNPM_HOME=/home/u/.local/share/pnpm
+ *
+ * Returns null for non-pnpm installs or a `packageRoot` with no `/global/`
+ * segment (nothing to derive from). Reading it from the running install is more
+ * accurate than trusting the inherited environment: it names the exact copy
+ * that is actually on PATH.
+ */
+export declare function derivePnpmHome(install: RunningInstall): string | null;
+/**
+ * Environment for the pnpm self-update spawn. `pnpm add -g` aborts with
+ * `ERR_PNPM_NO_GLOBAL_BIN_DIR` (exit 1) when neither `PNPM_HOME` nor a
+ * `global-bin-dir` setting is present — the exact failure seen when `hq`
+ * self-updates from a minimal-environment parent (a systemd `--user` service,
+ * cron, or any non-login shell that never sourced the profile exporting
+ * `PNPM_HOME`). When the running install is pnpm-managed and the parent lacks
+ * `PNPM_HOME`, inject one derived from the install's own path so the update can
+ * find the global bin dir it is about to rewrite.
+ *
+ * A no-op for npm/bun installs, and for any environment that already sets
+ * `PNPM_HOME` (never overridden — the caller's value wins). Returns `undefined`
+ * when nothing needs injecting, so callers can spawn with the inherited
+ * environment unchanged (and pass no `env` at all).
+ */
+export declare function pnpmUpdateEnv(install: RunningInstall, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv | undefined;
 export declare function buildPrefixedInstallArgv(prefix: string): string[];
 /**
  * Argv for updating a pnpm-managed global install. `pnpm add -g` rewrites the
@@ -150,10 +179,10 @@ export type UpdateResult = {
     detail?: string;
     code?: string;
 };
-type UpdateRunner = (cmd: string, args: string[]) => UpdateResult;
+type UpdateRunner = (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
 export { buildSpawnPlan, quoteForWindowsShell };
-export declare function runUpdateCommand(cmd: string, args: string[]): UpdateResult;
-declare function performUpdateCommand(cmd: string, args: string[], runner?: UpdateRunner): 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;
 /**
  * Soft notify when the server says we're below `latestVersion` but still ≥
@@ -218,8 +247,10 @@ export declare const __test__: {
     buildPrefixedInstallArgv: typeof buildPrefixedInstallArgv;
     buildSpawnPlan: typeof buildSpawnPlan;
     cleanStalePartialInstall: typeof cleanStalePartialInstall;
+    derivePnpmHome: typeof derivePnpmHome;
     enforceUpdateRequired: typeof enforceUpdateRequired;
     isBunManagedPackageDir: typeof isBunManagedPackageDir;
+    pnpmUpdateEnv: typeof pnpmUpdateEnv;
     isPnpmManagedPackageDir: typeof isPnpmManagedPackageDir;
     npmPrefixFromPackageDir: typeof npmPrefixFromPackageDir;
     nudgeUpdateRecommended: typeof nudgeUpdateRecommended;