@indigoai-us/hq-cli 5.108.9 → 5.108.10

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.108.10] — 2026-09-05
+
 ## [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,43 @@ 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;
+/**
+ * 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`.
+ */
+export declare function settingsWireV2Adapter(hqRoot: string): 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

@@ -51,6 +51,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 +129,117 @@ 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;
+    }
+}
+/**
+ * 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`.
+ */
+export function settingsWireV2Adapter(hqRoot) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(hqRoot, ".claude", "settings.json"), "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) &&
+        settingsWireV2Adapter(opts.hqRoot) &&
+        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 +252,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, settings wire 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 +482,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/package.json

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