@indigoai-us/hq-cli 5.102.0 → 5.103.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [5.103.0] — 2026-08-18
+
+### Added
+
+- `hq doctor` now checks the AI runtimes themselves, not just their hook
+  wiring. A new "AI runtime health" family verifies the `claude`, `codex`, and
+  `grok` CLIs are on PATH (a pure filesystem scan — the default run stays
+  offline; a missing CLI is WARN, never FAIL). A new `--live-runtimes` flag
+  additionally reads each installed CLI's version and sends it a one-line
+  prompt from a temp directory, proving the full binary → login → subscription
+  → response path; without the flag those checks report UNTESTED, so a
+  logged-out or broken runtime can no longer hide behind green wiring checks.
+
 ## [5.102.0] — 2026-08-17
 
 ### Added

package/dist/commands/agents.d.ts

@@ -15,6 +15,9 @@
  *   hq agents start|stop <uid>     — EC2 start/stop
  *   hq agents retry <uid>          — resume setup from first non-done step
  *   hq agents rm <uid> --yes       — deprovision (destructive; flag-guarded)
+ *   hq agents jobs list <uid>      — off-box job roster (schedule + rate)
+ *   hq agents jobs pause <uid> <jobId>  — flip schedule State=DISABLED
+ *   hq agents jobs cancel <uid> <jobId> — delete schedule + drop the job
  *
  * Agents are company-scoped. `--company <slug>` may sit on the group
  * (`hq agents --company acme list`) or on a subcommand
@@ -204,6 +207,46 @@ export declare function deprovisionAgent(token: string, agentUid: string): Promi
     setupState?: string;
     terminal?: boolean;
 }>;
+/** EventBridge Scheduler State as the operator list/pause surface reports it. */
+export type JobScheduleState = "ENABLED" | "DISABLED";
+/** One operator list row from `GET /v1/agents/{uid}/jobs`. */
+export interface AgentJobView {
+    jobId: string;
+    scheduleState: JobScheduleState | string;
+    rate: string;
+    lastRunOutcome: string | null;
+    status?: string;
+    nextRunAt?: string | null;
+    lastRunAt?: string | null;
+    prompt?: string;
+}
+export interface PauseJobResult {
+    ok: true;
+    jobId: string;
+    scheduleState: "DISABLED" | string;
+    changed: boolean;
+    previousState?: string;
+}
+export interface CancelJobResult {
+    ok: true;
+    jobId: string;
+}
+export declare function listAgentJobs(token: string, agentUid: string): Promise<AgentJobView[]>;
+export declare function pauseAgentJob(token: string, agentUid: string, jobId: string): Promise<PauseJobResult>;
+export declare function cancelAgentJob(token: string, agentUid: string, jobId: string): Promise<CancelJobResult>;
+/**
+ * Map a jobs-control HTTP error to a single operator-facing line. Pure so the
+ * status/code → copy mapping is unit-tested without a process exit.
+ *
+ * 404 without `JOB_NOT_FOUND` is also the deploy-order-safe path: hq-cli
+ * shipped before the hq-pro endpoints exist (or the agents flag is OFF, or
+ * the agent is cross-company) must print a clear message and exit non-zero,
+ * never throw a stack trace.
+ */
+export declare function formatJobsHttpError(err: AgentsHttpError, jobId?: string): string;
+/** Stable padEnd table: jobId, scheduleState, rate, lastRunOutcome, status. */
+export declare function formatJobsTable(jobs: AgentJobView[]): string;
+export declare function formatPauseResult(result: PauseJobResult): string;
 /** Human-readable "hot-applied to the running box" vs "saved for next launch". */
 export declare function appliedHint(applied: boolean): string;
 /** One message in a DM thread, as returned by `GET /v1/notify/thread`. */

package/dist/commands/agents.js

@@ -15,6 +15,9 @@
  *   hq agents start|stop <uid>     — EC2 start/stop
  *   hq agents retry <uid>          — resume setup from first non-done step
  *   hq agents rm <uid> --yes       — deprovision (destructive; flag-guarded)
+ *   hq agents jobs list <uid>      — off-box job roster (schedule + rate)
+ *   hq agents jobs pause <uid> <jobId>  — flip schedule State=DISABLED
+ *   hq agents jobs cancel <uid> <jobId> — delete schedule + drop the job
  *
  * Agents are company-scoped. `--company <slug>` may sit on the group
  * (`hq agents --company acme list`) or on a subcommand
@@ -309,6 +312,79 @@ export async function deprovisionAgent(token, agentUid) {
         method: "DELETE",
     });
 }
+export async function listAgentJobs(token, agentUid) {
+    const data = await agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/jobs`,
+    });
+    return data.jobs ?? [];
+}
+export async function pauseAgentJob(token, agentUid, jobId) {
+    return agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/jobs/${encodeURIComponent(jobId)}/pause`,
+        method: "POST",
+    });
+}
+export async function cancelAgentJob(token, agentUid, jobId) {
+    return agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/jobs/${encodeURIComponent(jobId)}/cancel`,
+        method: "POST",
+    });
+}
+/**
+ * Map a jobs-control HTTP error to a single operator-facing line. Pure so the
+ * status/code → copy mapping is unit-tested without a process exit.
+ *
+ * 404 without `JOB_NOT_FOUND` is also the deploy-order-safe path: hq-cli
+ * shipped before the hq-pro endpoints exist (or the agents flag is OFF, or
+ * the agent is cross-company) must print a clear message and exit non-zero,
+ * never throw a stack trace.
+ */
+export function formatJobsHttpError(err, jobId) {
+    if (err.status === 401)
+        return "Not authenticated — run `hq login`.";
+    if (err.status === 403)
+        return "You need owner/admin on this company.";
+    if (err.status === 404 && err.code === "JOB_NOT_FOUND") {
+        const id = jobId ?? extractQuotedJobId(err.message) ?? "unknown";
+        return `Job '${id}' not found.`;
+    }
+    if (err.status === 404)
+        return "Agent not found or not accessible.";
+    if (err.code === "JOBS_SCHEDULER_UNAVAILABLE" ||
+        err.code === "SCHEDULE_DELETE_FAILED") {
+        return `${err.code}: ${err.message}`;
+    }
+    return err.message;
+}
+function extractQuotedJobId(message) {
+    const m = message.match(/Job '([^']+)'/i);
+    return m?.[1];
+}
+/** Stable padEnd table: jobId, scheduleState, rate, lastRunOutcome, status. */
+export function formatJobsTable(jobs) {
+    if (jobs.length === 0)
+        return "No jobs.";
+    const cols = ["JOB_ID", "STATE", "RATE", "LAST_RUN", "STATUS"];
+    const rows = jobs.map((j) => [
+        j.jobId,
+        String(j.scheduleState ?? ""),
+        j.rate ?? "",
+        j.lastRunOutcome ?? "-",
+        j.status ?? "",
+    ]);
+    const widths = cols.map((c, i) => Math.max(c.length, ...rows.map((r) => r[i].length)));
+    const render = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ");
+    return [chalk.bold(render(cols)), ...rows.map(render)].join("\n");
+}
+export function formatPauseResult(result) {
+    if (!result.changed)
+        return "Already paused";
+    const from = result.previousState ?? "ENABLED";
+    return `Paused ${result.jobId} (${from} → ${result.scheduleState})`;
+}
 /** Human-readable "hot-applied to the running box" vs "saved for next launch". */
 export function appliedHint(applied) {
     return applied
@@ -394,6 +470,13 @@ function fail(err) {
     }
     process.exit(1);
 }
+function failJobs(err, jobId) {
+    if (err instanceof AgentsHttpError) {
+        console.error(chalk.red(formatJobsHttpError(err, jobId)));
+        process.exit(1);
+    }
+    fail(err);
+}
 export function registerAgentsCommand(program) {
     const agents = program
         .command("agents")
@@ -842,5 +925,59 @@ export function registerAgentsCommand(program) {
             fail(err);
         }
     });
+    // Off-box job control (US-003). Nested group so `hq agents jobs --help`
+    // lists list|pause|cancel. Same vaultApiFetch + person JWT as the rest of
+    // this file; keyed HQ_API_KEY rewrites /v1/agents → /v1/keys/agents.
+    const jobs = agents
+        .command("jobs")
+        .description("List, pause, or cancel an agent's scheduled jobs");
+    jobs
+        .command("list <agentUid>")
+        .description("List an agent's scheduled jobs")
+        .option("--json", "Emit raw JSON")
+        .action(async (agentUid, opts) => {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const roster = await listAgentJobs(token, agentUid);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(roster, null, 2) + "\n");
+                return;
+            }
+            if (roster.length === 0) {
+                console.log(chalk.gray("No jobs."));
+                return;
+            }
+            console.log(formatJobsTable(roster));
+        }
+        catch (err) {
+            failJobs(err);
+        }
+    });
+    jobs
+        .command("pause <agentUid> <jobId>")
+        .description("Pause a job's schedule (reversible)")
+        .action(async (agentUid, jobId) => {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await pauseAgentJob(token, agentUid, jobId);
+            console.log(chalk.green(formatPauseResult(result)));
+        }
+        catch (err) {
+            failJobs(err, jobId);
+        }
+    });
+    jobs
+        .command("cancel <agentUid> <jobId>")
+        .description("Cancel a job and delete its schedule")
+        .action(async (agentUid, jobId) => {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await cancelAgentJob(token, agentUid, jobId);
+            console.log(chalk.green(`Cancelled ${result.jobId}.`));
+        }
+        catch (err) {
+            failJobs(err, jobId);
+        }
+    });
 }
 //# sourceMappingURL=agents.js.map

package/dist/commands/doctor.d.ts

@@ -8,7 +8,9 @@
  *   - Running outside any HQ tree exits non-zero with a message naming exactly
  *     what it looked for — never a throw, never a false PASS.
  *   - The command performs no network calls and needs no authentication; it is
- *     purely a function of the on-disk shape of the tree.
+ *     purely a function of the on-disk shape of the tree. `--live-runtimes` is
+ *     the one opt-in exception: it probes the installed AI CLIs (claude, codex,
+ *     grok) with a version read and a one-line prompt.
  *
  * US-015 adds reporting, `--json`, and the exit-code contract: the exit code is
  * 0 unless some result is FAIL or UNKNOWN (WARN/UNTESTED/NA/KNOWN-DEFECT never
@@ -77,6 +79,13 @@ export interface RunDoctorOptions {
      * does — so a plain `hq doctor` stays purely a function of the on-disk shape.
      */
     deepTest?: boolean;
+    /**
+     * Additionally probe each installed AI CLI (claude, codex, grok) with a
+     * version read and a one-line prompt (`--live-runtimes`). Off by default:
+     * this is the doctor's only networked tier, and without it the runtime-health
+     * family reports UNTESTED rather than spawning anything.
+     */
+    liveRuntimes?: boolean;
 }
 /** The outcome of a doctor run, returned rather than thrown so it is testable. */
 export interface RunDoctorResult {

package/dist/commands/doctor.js

@@ -8,7 +8,9 @@
  *   - Running outside any HQ tree exits non-zero with a message naming exactly
  *     what it looked for — never a throw, never a false PASS.
  *   - The command performs no network calls and needs no authentication; it is
- *     purely a function of the on-disk shape of the tree.
+ *     purely a function of the on-disk shape of the tree. `--live-runtimes` is
+ *     the one opt-in exception: it probes the installed AI CLIs (claude, codex,
+ *     grok) with a version read and a one-line prompt.
  *
  * US-015 adds reporting, `--json`, and the exit-code contract: the exit code is
  * 0 unless some result is FAIL or UNKNOWN (WARN/UNTESTED/NA/KNOWN-DEFECT never
@@ -99,6 +101,7 @@ export async function runDoctor(options = {}) {
         hqRoot,
         platform: { id: platform.id, evidence: platform.evidence },
         sessionId: options.sessionId,
+        liveRuntimes: options.liveRuntimes === true,
     };
     const families = await registry.run(context);
     // `--deep-test` (US-008): after the read-only tiers, actually fire pure-guard
@@ -147,12 +150,13 @@ export async function runDoctor(options = {}) {
 export function registerDoctorCommand(program) {
     program
         .command("doctor")
-        .description("Verify HQ hook guardrails are wired and firing (read-only, offline).")
+        .description("Verify HQ hook guardrails are wired and firing (read-only, offline; --live-runtimes adds networked AI CLI probes).")
         .option("--json", "Emit the machine-readable JSON document (no colour).")
         .option("--verbose", "Also print every PASS result in text output.")
         .option("--no-color", "Disable ANSI colour even on a TTY.")
         .option("--session-id <id>", "Scope the runtime probe's ledger check to this exact session.")
         .option("--deep-test", "Also fire pure-guard hooks through the real gate under all three profiles (sandboxed).")
+        .option("--live-runtimes", "Also probe each installed AI CLI (claude, codex, grok) with a one-line prompt to verify login and subscription (networked; uses your subscriptions).")
         .option("--fix", "Apply the allowlisted safe repairs (backs up first; read-only without this flag).")
         .option("--yes", "Skip the interactive --fix confirmation (non-interactive use).")
         .option("--force", "Let --fix run despite uncommitted changes under .claude/, .codex/, or .grok/.")
@@ -199,6 +203,7 @@ export function registerDoctorCommand(program) {
             platform,
             sessionId: opts.sessionId,
             deepTest: opts.deepTest === true,
+            liveRuntimes: opts.liveRuntimes === true,
         });
         // Set the exit code rather than calling process.exit, so the CLI's
         // normal shutdown (telemetry flush) still runs. Non-zero means either an

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;

package/dist/utils/version-gate.js

@@ -167,6 +167,51 @@ export function resolveRunningManager() {
 export function resolveRunningPrefix() {
     return resolveRunningInstall().prefix;
 }
+/**
+ * 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 function derivePnpmHome(install) {
+    if (install.manager !== "pnpm" || !install.packageRoot)
+        return null;
+    const normalized = install.packageRoot.replace(/\\/g, "/");
+    const marker = normalized.indexOf("/global/");
+    if (marker === -1)
+        return null;
+    const home = normalized.slice(0, marker);
+    return home || 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 function pnpmUpdateEnv(install, base = process.env) {
+    if (install.manager !== "pnpm" || base.PNPM_HOME)
+        return undefined;
+    const home = derivePnpmHome(install);
+    if (!home)
+        return undefined;
+    return { ...base, PNPM_HOME: home };
+}
 export function buildPrefixedInstallArgv(prefix) {
     return ["install", "-g", "--prefix", prefix, LATEST_PACKAGE_SPEC];
 }
@@ -307,12 +352,13 @@ async function fetchVersionDecision() {
 // public surface (and the `__test__` block below) stable for existing callers
 // and tests.
 export { buildSpawnPlan, quoteForWindowsShell };
-export function runUpdateCommand(cmd, args) {
+export function runUpdateCommand(cmd, args, env) {
     try {
         const plan = buildSpawnPlan(cmd, args);
         const result = spawnSync(plan.cmd, plan.args, {
             stdio: "inherit",
             shell: plan.shell,
+            ...(env ? { env } : {}),
         });
         // spawnSync reports a missing executable via `error`, not a throw.
         if (result.error) {
@@ -335,8 +381,11 @@ export function runUpdateCommand(cmd, args) {
         };
     }
 }
-function performUpdateCommand(cmd, args, runner = runUpdateCommand) {
-    return runner(cmd, args);
+function performUpdateCommand(cmd, args, runner = runUpdateCommand, env) {
+    // Forward env only when there is one to forward, so the common path keeps the
+    // two-argument runner call it has always made (and existing runner spies see
+    // no phantom `undefined` third argument).
+    return env === undefined ? runner(cmd, args) : runner(cmd, args, env);
 }
 function performUpdate(command, runner = runUpdateCommand) {
     const parts = command.split(/\s+/).filter(Boolean);
@@ -442,11 +491,17 @@ function enforceUpdateRequired(decision, deps = {}) {
         primaryCmd = parts[0] ?? "";
         primaryArgs = parts.slice(1);
     }
+    // A pnpm global install needs PNPM_HOME to locate its global bin dir; a
+    // minimal-environment parent (systemd, cron, non-login shell) lacks it and
+    // `pnpm add -g` would abort with ERR_PNPM_NO_GLOBAL_BIN_DIR. Derive one from
+    // the running install so the update is not environment-dependent. No-op for
+    // npm/bun and when PNPM_HOME is already set.
+    const updateEnv = pnpmUpdateEnv(install);
     let result;
     if (isManagedOutsideNpm) {
         console.error(chalk.dim(`  Detected a ${install.manager}-managed global install; updating with ${install.manager}`));
         console.error(chalk.dim(`  Running: ${primaryCmd} ${primaryArgs.join(" ")}`));
-        result = performUpdateCommand(primaryCmd, primaryArgs, runner);
+        result = performUpdateCommand(primaryCmd, primaryArgs, runner, updateEnv);
     }
     else if (prefix) {
         console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
@@ -558,8 +613,10 @@ export const __test__ = {
     buildPrefixedInstallArgv,
     buildSpawnPlan,
     cleanStalePartialInstall,
+    derivePnpmHome,
     enforceUpdateRequired,
     isBunManagedPackageDir,
+    pnpmUpdateEnv,
     isPnpmManagedPackageDir,
     npmPrefixFromPackageDir,
     nudgeUpdateRecommended,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.102.0",
+  "version": "5.103.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {