@indigoai-us/hq-cli 5.108.10 → 5.108.11

package/CHANGELOG.md

@@ -2,8 +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

@@ -129,11 +129,36 @@ export interface AgentsV2AttestationOptions {
  */
 export declare function isAgentsV2Runtime(hqRoot: string, env?: NodeJS.ProcessEnv): boolean;
 /**
- * Whether `.claude/settings.json` wires the on-box agents-v2 hook adapter — a
- * raw substring match on the file, exactly like the shell's
- * `grep -q 'hq-agents-v2-hook-adapter\.sh'` in `hq_settings_wires_v2_adapter`.
+ * 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 function settingsWireV2Adapter(hqRoot: string): boolean;
+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

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. */
@@ -160,14 +161,47 @@ function readRuntimeMarkerMode(markerPath) {
     }
 }
 /**
- * Whether `.claude/settings.json` wires the on-box agents-v2 hook adapter — a
- * raw substring match on the file, exactly like the shell's
- * `grep -q 'hq-agents-v2-hook-adapter\.sh'` in `hq_settings_wires_v2_adapter`.
+ * 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 function settingsWireV2Adapter(hqRoot) {
+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(path.join(hqRoot, ".claude", "settings.json"), "utf8");
+        raw = fs.readFileSync(resolveHermesConfigPath(env), "utf8");
     }
     catch {
         return false;
@@ -237,7 +271,7 @@ function ledgerDirHasFreshTxt(dir, cutoffMs) {
 export function agentsV2Attested(opts) {
     const env = opts.env ?? process.env;
     return (isAgentsV2Runtime(opts.hqRoot, env) &&
-        settingsWireV2Adapter(opts.hqRoot) &&
+        runtimeConfigWiresV2Adapter(opts.hqRoot, env) &&
         v2LedgerPresent({ ...opts, env }));
 }
 /**
@@ -256,7 +290,7 @@ export function checkRuntimeProbe(context) {
     // 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, settings wire the on-box adapter, and a
+    // 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().

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.10",
+  "version": "5.108.11",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {