@indigoai-us/hq-cli 5.108.9 → 5.108.11

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [5.108.11] — 2026-09-05
+
+## [5.108.10] — 2026-09-05
+
+### Fixed
+
+- `hq doctor` now self-attests hook enforcement on agents-v2 (hermes) fleet
+  hosts, which host detection leaves platform-unknown. When the runtime is
+  agents-v2 (the runtime marker reports `agents-v2`, or the on-box hook adapter
+  is installed under the tree), `.claude/settings.json` wires that on-box
+  adapter, and a policy-trigger ledger evidences a live turn (the exact
+  session's ledger under `--session-id`, otherwise any ledger fresh within the
+  freshness window), the runtime probe reports platform `agents-v2` and PASS
+  instead of UNKNOWN — because the on-box adapter provably wrote the ledger
+  through the same `.claude` hooks. This is the TypeScript twin of
+  `agents_v2_attested` in `check-hq-hooks.sh`; all three signals are required, so
+  no non-agents-v2 host's verdict changes.
+
 ## [5.108.9] — 2026-09-05
 
 ## [5.108.8] — 2026-09-05

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

@@ -49,6 +49,25 @@ export declare const RUNTIME_PROBE_PREFIX = "hooks.runtime";
 export declare const POLICY_TRIGGER_LEDGER_RELPATH = "workspace/orchestrator/policy-trigger-state";
 /** The two lifecycle events `check-hq-hooks.sh` requires a command hook on. */
 export declare const REQUIRED_HOOK_EVENTS: readonly ["SessionStart", "PreToolUse"];
+/**
+ * Default runtime marker path an agents-v2 (hermes) box writes its runtime mode
+ * to. Overridable via `HQ_RUNTIME_MARKER_FILE`, exactly as the shell reads
+ * `${HQ_RUNTIME_MARKER_FILE:-/var/lib/hq-agent/runtime.json}`.
+ */
+export declare const HQ_RUNTIME_MARKER_DEFAULT = "/var/lib/hq-agent/runtime.json";
+/**
+ * Path (relative to the HQ root) of the on-box agents-v2 hook adapter. Its
+ * presence under the tree is one of the two signals that the runtime is
+ * agents-v2, mirroring `hq_runtime_mode` in `check-hq-hooks.sh`.
+ */
+export declare const AGENTS_V2_ADAPTER_RELPATH = ".agents-v2-hooks/hq-agents-v2-hook-adapter.sh";
+/**
+ * Default hours a policy-trigger ledger may age and still evidence a live
+ * agents-v2 turn when no exact session id is given. Overridable via
+ * `HQ_V2_LEDGER_MAX_AGE_HOURS`, matching the shell's
+ * `HQ_V2_LEDGER_MAX_AGE_HOURS="${HQ_V2_LEDGER_MAX_AGE_HOURS:-24}"`.
+ */
+export declare const HQ_V2_LEDGER_MAX_AGE_HOURS_DEFAULT = 24;
 /** Whether the ledger was found. Mirrors the script's `present`/`missing`. */
 export type LedgerState = "present" | "missing";
 /** Options for {@link reproduceCheckHqHooks}. */
@@ -92,6 +111,68 @@ export interface HookLoadReproduction {
  * exception, so the probe degrades exactly like the defensively-written script.
  */
 export declare function reproduceCheckHqHooks(opts: ReproduceOptions): HookLoadReproduction;
+/** Inputs for the agents-v2 attestation helpers. */
+export interface AgentsV2AttestationOptions {
+    /** Absolute HQ tree root. */
+    hqRoot: string;
+    /** Optional session scope for the ledger check (the `--session-id` flag). */
+    sessionId?: string;
+    /** Environment to read (marker path, freshness window). Default: process.env. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Whether the runtime is agents-v2. Two signals, either sufficient — the same
+ * two `hq_runtime_mode` uses: the runtime marker
+ * (`HQ_RUNTIME_MARKER_FILE`, default {@link HQ_RUNTIME_MARKER_DEFAULT}) reads
+ * `runtimeMode == "agents-v2"`, OR the on-box adapter is installed under the
+ * tree at {@link AGENTS_V2_ADAPTER_RELPATH}.
+ */
+export declare function isAgentsV2Runtime(hqRoot: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Env var overriding the agents-v2 runtime (hermes) config path (chiefly for
+ * tests), mirroring `HQ_RUNTIME_MARKER_FILE` and the shell's
+ * `HQ_HERMES_CONFIG_FILE`.
+ */
+export declare const HQ_HERMES_CONFIG_ENV = "HQ_HERMES_CONFIG_FILE";
+/**
+ * The agents-v2 runtime (hermes) config whose `hooks:` block wires the on-box
+ * adapter into every lifecycle event — the env override, else `~/.hermes/config.yaml`
+ * (where `provision/render-config.sh` renders it). Mirrors the shell's
+ * `HQ_HERMES_CONFIG_FILE="${HQ_HERMES_CONFIG_FILE:-$HOME/.hermes/config.yaml}"`.
+ */
+export declare function resolveHermesConfigPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Whether the agents-v2 runtime actually wires the on-box hook adapter.
+ *
+ * The wiring lives in the RUNTIME's hook config, not `.claude/settings.json`. On
+ * a real box the v2 runtime's shell-hook dispatcher (`agent/shell_hooks.py`)
+ * reads a `hooks:` block from `~/.hermes/config.yaml` with one entry per
+ * lifecycle event, each invoking `hq-agents-v2-hook-adapter.sh`; the adapter in
+ * turn READS `.claude/settings.json` (via `hook-adapter-core.sh`) to fan out to
+ * the classic `.claude/hooks` set. So `.claude/settings.json` never NAMES the
+ * adapter — it wires the classic `hook-gate.sh` hooks — and grepping it for the
+ * adapter always fails on a real box (verified on the v2.17 canary
+ * i-0277243ad3aed8109, 2026-09-05: settings.json had 0 adapter refs / 94
+ * hook-gate.sh refs, while ~/.hermes/config.yaml wired the adapter across 7
+ * events). Require BOTH the adapter installed under the tree at
+ * {@link AGENTS_V2_ADAPTER_RELPATH} AND the runtime config invoking it. Mirrors
+ * `hq_runtime_config_wires_v2_adapter` in `check-hq-hooks.sh`.
+ */
+export declare function runtimeConfigWiresV2Adapter(hqRoot: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether a policy-trigger ledger evidencing a live agents-v2 turn is present:
+ * the exact session's ledger when a session id is given (session identity
+ * implies freshness), otherwise any ledger modified within the freshness window
+ * so a long-dead tree cannot self-attest off a stale file. Mirrors
+ * `hq_v2_ledger_present`.
+ */
+export declare function v2LedgerPresent(opts: AgentsV2AttestationOptions): boolean;
+/**
+ * All three agents-v2 self-attestation conditions. Used only to GRANT PASS to a
+ * hermes box that host detection leaves platform-unknown; never to withhold it.
+ * The exact conjunction of `agents_v2_attested` in `check-hq-hooks.sh`.
+ */
+export declare function agentsV2Attested(opts: AgentsV2AttestationOptions): boolean;
 /**
  * The runtime-probe check family entry. Reproduces the script verdict, then
  * renders it as a single platform-aware doctor result. See the module header for

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

@@ -38,6 +38,7 @@
  * very evidence it is looking for.
  */
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { scanHookCommand } from "./claude-wiring.js";
 /** Common id prefix for every result the runtime probe emits. */
@@ -51,6 +52,25 @@ export const RUNTIME_PROBE_PREFIX = "hooks.runtime";
 export const POLICY_TRIGGER_LEDGER_RELPATH = "workspace/orchestrator/policy-trigger-state";
 /** The two lifecycle events `check-hq-hooks.sh` requires a command hook on. */
 export const REQUIRED_HOOK_EVENTS = ["SessionStart", "PreToolUse"];
+/**
+ * Default runtime marker path an agents-v2 (hermes) box writes its runtime mode
+ * to. Overridable via `HQ_RUNTIME_MARKER_FILE`, exactly as the shell reads
+ * `${HQ_RUNTIME_MARKER_FILE:-/var/lib/hq-agent/runtime.json}`.
+ */
+export const HQ_RUNTIME_MARKER_DEFAULT = "/var/lib/hq-agent/runtime.json";
+/**
+ * Path (relative to the HQ root) of the on-box agents-v2 hook adapter. Its
+ * presence under the tree is one of the two signals that the runtime is
+ * agents-v2, mirroring `hq_runtime_mode` in `check-hq-hooks.sh`.
+ */
+export const AGENTS_V2_ADAPTER_RELPATH = ".agents-v2-hooks/hq-agents-v2-hook-adapter.sh";
+/**
+ * Default hours a policy-trigger ledger may age and still evidence a live
+ * agents-v2 turn when no exact session id is given. Overridable via
+ * `HQ_V2_LEDGER_MAX_AGE_HOURS`, matching the shell's
+ * `HQ_V2_LEDGER_MAX_AGE_HOURS="${HQ_V2_LEDGER_MAX_AGE_HOURS:-24}"`.
+ */
+export const HQ_V2_LEDGER_MAX_AGE_HOURS_DEFAULT = 24;
 /**
  * Faithfully reproduce `core/scripts/check-hq-hooks.sh --require-ledger` in
  * TypeScript. The checks, in the script's order:
@@ -110,6 +130,150 @@ export function reproduceCheckHqHooks(opts) {
     }
     return { ok: issues.length === 0, ledgerState, issues };
 }
+/**
+ * Whether the runtime is agents-v2. Two signals, either sufficient — the same
+ * two `hq_runtime_mode` uses: the runtime marker
+ * (`HQ_RUNTIME_MARKER_FILE`, default {@link HQ_RUNTIME_MARKER_DEFAULT}) reads
+ * `runtimeMode == "agents-v2"`, OR the on-box adapter is installed under the
+ * tree at {@link AGENTS_V2_ADAPTER_RELPATH}.
+ */
+export function isAgentsV2Runtime(hqRoot, env = process.env) {
+    const markerPath = env.HQ_RUNTIME_MARKER_FILE?.trim() || HQ_RUNTIME_MARKER_DEFAULT;
+    if (readRuntimeMarkerMode(markerPath) === "agents-v2")
+        return true;
+    return isFile(path.join(hqRoot, ...AGENTS_V2_ADAPTER_RELPATH.split("/")));
+}
+/** The `runtimeMode` field of the runtime marker JSON, or null when unreadable. */
+function readRuntimeMarkerMode(markerPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(markerPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.runtimeMode === "string" ? parsed.runtimeMode : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Env var overriding the agents-v2 runtime (hermes) config path (chiefly for
+ * tests), mirroring `HQ_RUNTIME_MARKER_FILE` and the shell's
+ * `HQ_HERMES_CONFIG_FILE`.
+ */
+export const HQ_HERMES_CONFIG_ENV = "HQ_HERMES_CONFIG_FILE";
+/**
+ * The agents-v2 runtime (hermes) config whose `hooks:` block wires the on-box
+ * adapter into every lifecycle event — the env override, else `~/.hermes/config.yaml`
+ * (where `provision/render-config.sh` renders it). Mirrors the shell's
+ * `HQ_HERMES_CONFIG_FILE="${HQ_HERMES_CONFIG_FILE:-$HOME/.hermes/config.yaml}"`.
+ */
+export function resolveHermesConfigPath(env = process.env) {
+    const override = env[HQ_HERMES_CONFIG_ENV]?.trim();
+    if (override)
+        return override;
+    return path.join(os.homedir(), ".hermes", "config.yaml");
+}
+/**
+ * Whether the agents-v2 runtime actually wires the on-box hook adapter.
+ *
+ * The wiring lives in the RUNTIME's hook config, not `.claude/settings.json`. On
+ * a real box the v2 runtime's shell-hook dispatcher (`agent/shell_hooks.py`)
+ * reads a `hooks:` block from `~/.hermes/config.yaml` with one entry per
+ * lifecycle event, each invoking `hq-agents-v2-hook-adapter.sh`; the adapter in
+ * turn READS `.claude/settings.json` (via `hook-adapter-core.sh`) to fan out to
+ * the classic `.claude/hooks` set. So `.claude/settings.json` never NAMES the
+ * adapter — it wires the classic `hook-gate.sh` hooks — and grepping it for the
+ * adapter always fails on a real box (verified on the v2.17 canary
+ * i-0277243ad3aed8109, 2026-09-05: settings.json had 0 adapter refs / 94
+ * hook-gate.sh refs, while ~/.hermes/config.yaml wired the adapter across 7
+ * events). Require BOTH the adapter installed under the tree at
+ * {@link AGENTS_V2_ADAPTER_RELPATH} AND the runtime config invoking it. Mirrors
+ * `hq_runtime_config_wires_v2_adapter` in `check-hq-hooks.sh`.
+ */
+export function runtimeConfigWiresV2Adapter(hqRoot, env = process.env) {
+    const adapter = path.join(hqRoot, ...AGENTS_V2_ADAPTER_RELPATH.split("/"));
+    if (!isFile(adapter))
+        return false;
+    let raw;
+    try {
+        raw = fs.readFileSync(resolveHermesConfigPath(env), "utf8");
+    }
+    catch {
+        return false;
+    }
+    return raw.includes("hq-agents-v2-hook-adapter.sh");
+}
+/**
+ * Whether a policy-trigger ledger evidencing a live agents-v2 turn is present:
+ * the exact session's ledger when a session id is given (session identity
+ * implies freshness), otherwise any ledger modified within the freshness window
+ * so a long-dead tree cannot self-attest off a stale file. Mirrors
+ * `hq_v2_ledger_present`.
+ */
+export function v2LedgerPresent(opts) {
+    const env = opts.env ?? process.env;
+    const dir = path.join(opts.hqRoot, ...POLICY_TRIGGER_LEDGER_RELPATH.split("/"));
+    if (!isDir(dir))
+        return false;
+    if (opts.sessionId) {
+        return isFile(path.join(dir, `${opts.sessionId}.txt`));
+    }
+    const cutoffMs = Date.now() - resolveMaxLedgerAgeHours(env) * 60 * 60 * 1000;
+    return ledgerDirHasFreshTxt(dir, cutoffMs);
+}
+/** The freshness window in hours, from the env override or the default. */
+function resolveMaxLedgerAgeHours(env) {
+    const raw = env.HQ_V2_LEDGER_MAX_AGE_HOURS?.trim();
+    if (!raw)
+        return HQ_V2_LEDGER_MAX_AGE_HOURS_DEFAULT;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed >= 0
+        ? parsed
+        : HQ_V2_LEDGER_MAX_AGE_HOURS_DEFAULT;
+}
+/** True when any `*.txt` under `dir` (recursive) was modified at/after `cutoffMs`. */
+function ledgerDirHasFreshTxt(dir, cutoffMs) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (ledgerDirHasFreshTxt(full, cutoffMs))
+                return true;
+        }
+        else if (entry.isFile() && entry.name.endsWith(".txt")) {
+            try {
+                if (fs.statSync(full).mtimeMs >= cutoffMs)
+                    return true;
+            }
+            catch {
+                // Unreadable entry: ignore, keep scanning.
+            }
+        }
+    }
+    return false;
+}
+/**
+ * All three agents-v2 self-attestation conditions. Used only to GRANT PASS to a
+ * hermes box that host detection leaves platform-unknown; never to withhold it.
+ * The exact conjunction of `agents_v2_attested` in `check-hq-hooks.sh`.
+ */
+export function agentsV2Attested(opts) {
+    const env = opts.env ?? process.env;
+    return (isAgentsV2Runtime(opts.hqRoot, env) &&
+        runtimeConfigWiresV2Adapter(opts.hqRoot, env) &&
+        v2LedgerPresent({ ...opts, env }));
+}
 /**
  * The runtime-probe check family entry. Reproduces the script verdict, then
  * renders it as a single platform-aware doctor result. See the module header for
@@ -122,6 +286,26 @@ export function checkRuntimeProbe(context) {
     const checkId = `${RUNTIME_PROBE_PREFIX}.enforcement`;
     const target = POLICY_TRIGGER_LEDGER_RELPATH;
     const scope = sessionId ? ` for session ${sessionId}` : "";
+    // agents-v2 (hermes) self-attestation. hq doctor leaves the hermes host
+    // platform-unknown and, on an unknown host, the probe would report UNKNOWN
+    // below. But the on-box adapter provably wrote the ledger through the same
+    // .claude hooks, so grant PASS — and report platform "agents-v2" — when, and
+    // only when, the runtime is agents-v2, the runtime config wires the on-box adapter, and a
+    // ledger exists (the exact session's under --session-id; otherwise any ledger
+    // fresh within the window). Requires the on-box marker/adapter, so this never
+    // changes the verdict for any other host. See agentsV2Attested().
+    if (agentsV2Attested({ hqRoot, sessionId })) {
+        return [
+            {
+                status: "PASS",
+                checkId,
+                target,
+                message: `Host platform is agents-v2 (hermes fleet): the on-box adapter wrote the ` +
+                    `policy-trigger ledger through the same .claude hooks, so hook dispatch was ` +
+                    `observed this session — the ledger has an entry${scope}.`,
+            },
+        ];
+    }
     const repro = reproduceCheckHqHooks({ hqRoot, sessionId });
     // Unknown host: the label cannot be trusted, so live enforcement cannot be
     // verified in either direction. UNKNOWN (never PASS or FAIL) is the honest
@@ -332,4 +516,12 @@ function isFile(file) {
         return false;
     }
 }
+function isDir(dir) {
+    try {
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=runtime-probe.js.map

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

@@ -74,6 +74,22 @@ export interface DeriveVerdictOptions {
      * inline script treats a missing ledger — regardless of platform.
      */
     requireLedger?: boolean;
+    /**
+     * Whether this is an attested agents-v2 (hermes) box: the runtime is
+     * agents-v2, `.claude/settings.json` wires the on-box adapter, and a
+     * policy-trigger ledger exists (the exact session's when a session id is
+     * given; otherwise a ledger fresh within the freshness window). When true,
+     * OBSERVED is granted even though the doctor's runtime check did not report
+     * PASS — because hq doctor leaves the hermes host platform-unknown, yet the
+     * on-box adapter provably wrote the ledger through the same .claude hooks.
+     *
+     * This is the exact twin of the `agents_v2_attested` override in
+     * `render_from_doctor` (`core/scripts/check-hq-hooks.sh`). Establish it with
+     * {@link agentsV2Attested} in `checks/runtime-probe.ts` — the same three
+     * signals the shell's `agents_v2_attested` reads. It can only GRANT OBSERVED,
+     * never withhold it, so every non-agents-v2 caller is unaffected.
+     */
+    agentsV2Attested?: boolean;
 }
 /**
  * Derive the check-hq-hooks.sh verdict from a `hq doctor --json` document,

package/dist/lib/doctor/compat.js

@@ -80,7 +80,18 @@ export function deriveCheckHqHooksVerdict(doc, options = {}) {
     // for --require-ledger, matching the inline script's "fail on a missing
     // ledger" contract.
     const runtimeResult = doc.results.find((result) => result.checkId === RUNTIME_ENFORCEMENT_CHECK_ID);
-    const runtime = observeRuntime(runtimeResult?.status, requireLedger);
+    let runtime = observeRuntime(runtimeResult?.status, requireLedger);
+    // agents-v2 self-attestation: hq doctor leaves the hermes host
+    // platform-unknown and so does not report the runtime check as PASS, but the
+    // on-box adapter provably wrote the ledger through the same .claude hooks.
+    // Grant the identical OBSERVED verdict rather than relaying the host-unknown
+    // status as a failure. Mirrors render_from_doctor()'s agents_v2_attested
+    // override in check-hq-hooks.sh; only ever grants OBSERVED, never withholds it.
+    if (requireLedger &&
+        runtime !== "OBSERVED" &&
+        options.agentsV2Attested === true) {
+        runtime = "OBSERVED";
+    }
     if (requireLedger && runtime !== "OBSERVED") {
         messages.push(runtimeResult?.message ??
             "policy-trigger ledger was not found under workspace/orchestrator/policy-trigger-state");

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, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, checkUpdateConvergence, inOwnProcessGroup, isLocalDependencyInstall, isPrefixWritable, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
 /**
@@ -268,6 +268,13 @@ async function updateAndReexec(argv, flavor, known, deps) {
         console.error(chalk.yellow(`⚠ hq-cli ${latest} is available but the update failed` +
             `${result.detail ? `: ${result.detail}` : ""}`));
         console.error(chalk.dim(`  Try manually: ${plan.cmd} ${plan.args.join(" ")}`));
+        // A root-owned npm prefix the running user cannot write is the agent-box
+        // case (the CLI is a /usr global install and the runtime is unprivileged),
+        // and the startup path has no sudo fallback — say so plainly so a failed
+        // update on a box reads as the permission wall it is, not a transient error.
+        if (install.manager === "npm" && install.prefix && !isPrefixWritable(install.prefix)) {
+            console.error(chalk.yellow(`  ${nonWritablePrefixNote(install.prefix)}`));
+        }
         // A manager-level failure often means the install layout itself is broken
         // (e.g. a hand-rolled pnpm store nested inside the app's bin dir). The
         // manual retry above hits the same layout and fails the same way; point at

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

@@ -150,6 +150,30 @@ 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;
+/**
+ * Whether the current process can write the npm global `prefix` — i.e. whether
+ * an `npm install -g --prefix <prefix>` could actually replace the installed
+ * CLI, or would fail with EACCES.
+ *
+ * The path npm rewrites is the prefix's `bin` dir (`<prefix>/bin/hq` on unix
+ * globals — the `rename /usr/bin/hq` EACCES the agent boxes hit), so that is
+ * checked first; the prefix itself is the fallback for `--prefix` layouts that
+ * keep the bin beside `node_modules`. A missing dir (ENOENT) is treated as
+ * writable: npm would create it, and this check exists to explain a permission
+ * wall, not to second-guess a not-yet-created prefix.
+ *
+ * `access` is injected so the classification is unit-testable without a real
+ * root-owned prefix.
+ */
+export declare function isPrefixWritable(prefix: string, access?: (target: string, mode: number) => void): boolean;
+/**
+ * One-line operator explanation for a failed global update whose prefix the
+ * running user cannot write. This is the agent-box case: the CLI is a
+ * root-owned `/usr` global install and the runtime is unprivileged, so the
+ * update genuinely cannot converge from here and re-trying it silently would
+ * loop. Says so plainly and points at the paths that CAN update it.
+ */
+export declare function nonWritablePrefixNote(prefix: string): string;
 /**
  * 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
@@ -409,6 +433,8 @@ export declare const __test__: {
     isNewerVersion: typeof isNewerVersion;
     isPnpmManagedPackageDir: typeof isPnpmManagedPackageDir;
     isPnpmVirtualStorePackageDir: typeof isPnpmVirtualStorePackageDir;
+    isPrefixWritable: typeof isPrefixWritable;
+    nonWritablePrefixNote: typeof nonWritablePrefixNote;
     npmPrefixFromPackageDir: typeof npmPrefixFromPackageDir;
     nudgeUpdateRecommended: typeof nudgeUpdateRecommended;
     performUpdate: typeof performUpdate;

package/dist/utils/version-gate.js

@@ -29,7 +29,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
-import { closeSync, existsSync, mkdtempSync, openSync, readdirSync, readFileSync, rmSync, } from "node:fs";
+import { accessSync, closeSync, constants as fsConstants, existsSync, mkdtempSync, openSync, readdirSync, readFileSync, rmSync, } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -277,6 +277,50 @@ export function resolveRunningManager() {
 export function resolveRunningPrefix() {
     return resolveRunningInstall().prefix;
 }
+/**
+ * Whether the current process can write the npm global `prefix` — i.e. whether
+ * an `npm install -g --prefix <prefix>` could actually replace the installed
+ * CLI, or would fail with EACCES.
+ *
+ * The path npm rewrites is the prefix's `bin` dir (`<prefix>/bin/hq` on unix
+ * globals — the `rename /usr/bin/hq` EACCES the agent boxes hit), so that is
+ * checked first; the prefix itself is the fallback for `--prefix` layouts that
+ * keep the bin beside `node_modules`. A missing dir (ENOENT) is treated as
+ * writable: npm would create it, and this check exists to explain a permission
+ * wall, not to second-guess a not-yet-created prefix.
+ *
+ * `access` is injected so the classification is unit-testable without a real
+ * root-owned prefix.
+ */
+export function isPrefixWritable(prefix, access = (target, mode) => accessSync(target, mode)) {
+    for (const dir of [path.join(prefix, "bin"), prefix]) {
+        try {
+            access(dir, fsConstants.W_OK);
+            return true;
+        }
+        catch (err) {
+            // A dir that does not exist yet is not a permission wall — npm creates it.
+            if (err?.code === "ENOENT") {
+                return true;
+            }
+            // Any other error (EACCES/EPERM/EROFS) on this candidate: try the next.
+        }
+    }
+    return false;
+}
+/**
+ * One-line operator explanation for a failed global update whose prefix the
+ * running user cannot write. This is the agent-box case: the CLI is a
+ * root-owned `/usr` global install and the runtime is unprivileged, so the
+ * update genuinely cannot converge from here and re-trying it silently would
+ * loop. Says so plainly and points at the paths that CAN update it.
+ */
+export function nonWritablePrefixNote(prefix) {
+    return (`The npm global prefix ${prefix} is not writable by the current user, so this update cannot ` +
+        `take effect here. On an agent box this is expected: the CLI is a root-owned global install and ` +
+        `updates land as root — via the box's hq-cli-update timer, or \`sudo npm install -g ${CLI_NAME}@latest\` — ` +
+        `not from the unprivileged runtime.`);
+}
 /**
  * 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
@@ -907,6 +951,13 @@ function attemptRequiredUpdate(decision, deps, install) {
     }
     if (!result.ok) {
         console.error(chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`));
+        // A root-owned global prefix the running user cannot write is the agent-box
+        // case: even the `sudo -n` retry above cannot help without passwordless
+        // sudo, so name the wall plainly rather than leaving `exit 75` to read as a
+        // generic failure. Only for npm-prefix installs (pnpm/Bun route elsewhere).
+        if (!isManagedOutsideNpm && prefix && !isPrefixWritable(prefix)) {
+            console.error(chalk.yellow(`  ${nonWritablePrefixNote(prefix)}`));
+        }
         // The package manager itself is missing from this environment — the usual
         // cause is a minimal-PATH parent (launchd, cron, a bare systemd unit) that
         // never sourced the shell profile which puts PNPM_HOME (or nvm's npm) on
@@ -996,6 +1047,8 @@ export const __test__ = {
     isNewerVersion,
     isPnpmManagedPackageDir,
     isPnpmVirtualStorePackageDir,
+    isPrefixWritable,
+    nonWritablePrefixNote,
     npmPrefixFromPackageDir,
     nudgeUpdateRecommended,
     performUpdate,

package/package.json

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