@indigoai-us/hq-cli 5.108.10 → 5.108.12

package/CHANGELOG.md

@@ -2,8 +2,70 @@
 
 ## [Unreleased]
 
+## [5.108.12] - 2026-09-05
+
+### Fixed
+
+- `hq dm send` into a channel now turns `@name` in the message into a REAL
+  mention. HQ Rooms mentions are structured-only — the server never reads
+  `@name` out of the body — so until now a CLI post like
+  `hq dm send '#hq-dev' "@Izzy please look"` went in with no `mentions` array
+  and mentioned nobody: no notification, no agent wake. During an incident that
+  was a silent false negative, and it made agent-in-channel workflows
+  undrivable from the CLI. The send path now reads the channel roster
+  (`GET /v1/notify/channels/{id}/members`), resolves each `@name`
+  case-insensitively against display name, slug/handle, email local part, and
+  first name, and posts the structured `mentions` array with `participantType`
+  derived from the uid prefix (`agt_*` → agent, otherwise human). Quote a
+  multi-word name as `@"Jacob Posel"`. A name that is unknown or matches more
+  than one member FAILS the send and lists the roster or the candidates rather
+  than posting something that looks addressed but isn't; a bare `@` or an email
+  address in prose is never a mention. `--no-mentions` posts the text literally.
+
+## [5.108.11] — 2026-09-05
+
+### Fixed
+
+- `hq doctor` agents-v2 (hermes) self-attestation now keys hook-adapter wiring
+  on the **runtime config**, not `.claude/settings.json` (#512). The 5.108.10
+  fix required `.claude/settings.json` to name `hq-agents-v2-hook-adapter.sh`,
+  but on a real hermes box it never does: the v2 runtime's shell-hook dispatcher
+  reads a `hooks:` block from `~/.hermes/config.yaml` that invokes the adapter,
+  and the adapter merely *reads* `.claude/settings.json` to fan out to the
+  classic `hook-gate.sh` hooks. On the v2.17 canary `settings.json` had 0
+  adapter references / 94 `hook-gate.sh` references while `~/.hermes/config.yaml`
+  wired the adapter across its lifecycle events, so the old check could never
+  attest. The runtime probe now requires the on-box adapter installed under the
+  tree at `.agents-v2-hooks/hq-agents-v2-hook-adapter.sh` **and** the runtime
+  config at `${HQ_HERMES_CONFIG_FILE:-~/.hermes/config.yaml}` invoking it. All
+  three attestation signals are still required, and no non-agents-v2 host's
+  verdict changes. TypeScript twin of `hq_runtime_config_wires_v2_adapter` in
+  `check-hq-hooks.sh`.
+- `hq` self-update and the version-gate now name a non-writable npm prefix
+  plainly instead of failing opaquely (#511). When a global update fails because
+  the npm prefix is root-owned and the running user cannot write it — the
+  agent-box case, where the CLI is a `/usr` global install and the runtime is
+  unprivileged — both update surfaces now print that the prefix is not writable
+  and point at the paths that *can* update it (the box's `hq-cli-update` timer or
+  `sudo npm install -g @indigoai-us/hq-cli@latest`), rather than leaving
+  `exit 75` to read as a generic error.
+
 ## [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/commands/dm.d.ts

@@ -57,6 +57,70 @@ export interface ChannelSummary {
  * unit-testable.
  */
 export declare function matchChannelsByName(channels: ChannelSummary[], name: string): ChannelSummary[];
+/** Server-side cap on one post's mentions (hq-pro MAX_CHANNEL_MENTIONS). */
+export declare const MAX_CHANNEL_MENTIONS = 25;
+/**
+ * One roster row from GET /v1/notify/channels/{id}/members. The server enriches
+ * each CHAN_MEMBER row with live display identity (displayName, email, …).
+ */
+export interface ChannelMember {
+    personUid: string;
+    displayName?: string;
+    email?: string;
+    slug?: string;
+    handle?: string;
+}
+/** A structured mention as the POST messages route expects it. */
+export interface ChannelMention {
+    participantUid: string;
+    participantType: "agent" | "human";
+    displayName: string;
+}
+/**
+ * `agt_*` uids are agents, everything else (`prs_*`) is a human. The server
+ * 400s INVALID_MENTIONS when the type and the uid prefix disagree, so this is
+ * derived, never guessed.
+ */
+export declare function mentionParticipantType(uid: string): "agent" | "human";
+/**
+ * Extract `@name` tokens from a message body — leading or inline. A token is an
+ * `@` at a WORD BOUNDARY (start of body, or after whitespace or an opening
+ * bracket/quote) followed by a name run. Quote the `@` for a multi-word display
+ * name: `@"Jacob Posel"`. Pure → unit-testable.
+ *
+ *   'hi @Izzy please look'  → ["Izzy"]
+ *   '@"Jacob Posel" ping'   → ["Jacob Posel"]
+ *   'email a@b.com'         → []          (not a word boundary)
+ *   'cost is @ the top'     → []          (bare @)
+ *   '@izzy and @Izzy'       → ["izzy"]    (deduped case-insensitively)
+ *
+ * Trailing punctuation is trimmed ("@Izzy," → "Izzy"), so a name is never
+ * polluted by the sentence around it.
+ */
+export declare function parseMentionTokens(body: string): string[];
+/**
+ * The names one roster row answers to, lowercased: its display name, the slug of
+ * that display name, any server-supplied slug/handle, the email local part, and
+ * the first word of a multi-word display name (so `@Izzy` reaches "Izzy
+ * Rivera"). A key shared by two rows makes the token AMBIGUOUS, which fails the
+ * send — never a silent pick. Pure → unit-testable.
+ */
+export declare function memberMatchKeys(member: ChannelMember): string[];
+export type MentionResolution = {
+    ok: true;
+    mentions: ChannelMention[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve `@name` tokens against the channel roster into the structured
+ * `mentions` array. Case-insensitive on display name and slug/handle. Anything
+ * ambiguous (several roster rows answer to the name) or unresolvable (none do)
+ * FAILS with a message naming the candidates or the roster — the caller must
+ * never post a message whose "@" text mentions nobody. Pure → unit-testable.
+ */
+export declare function resolveMentions(tokens: string[], members: ChannelMember[]): MentionResolution;
 /**
  * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
  * Returns null on anything that doesn't match. Pure → unit-testable.

package/dist/commands/dm.js

@@ -101,6 +101,157 @@ export function matchChannelsByName(channels, name) {
         return false;
     });
 }
+// ─── Channel @mentions ───────────────────────────────────────────────────────
+//
+// HQ Rooms mentions are STRUCTURED ONLY: the server never parses `@name` out of
+// the message body (see hq-pro src/vault-service/lib/room-agent-delivery.ts and
+// parseChannelMentions / resolveChannelMentions in
+// src/vault-service/handlers/notify-dm.ts). A post whose body says "@Izzy please
+// look" but carries no `mentions` array mentions NOBODY — no notification, no
+// agent wake. That is a silent false negative during an incident, so the CLI
+// resolves the names itself and sends the structured array. Resolution failures
+// FAIL the send rather than posting a message that looks addressed but isn't.
+/** Server-side cap on one post's mentions (hq-pro MAX_CHANNEL_MENTIONS). */
+export const MAX_CHANNEL_MENTIONS = 25;
+/**
+ * `agt_*` uids are agents, everything else (`prs_*`) is a human. The server
+ * 400s INVALID_MENTIONS when the type and the uid prefix disagree, so this is
+ * derived, never guessed.
+ */
+export function mentionParticipantType(uid) {
+    return uid.startsWith("agt_") ? "agent" : "human";
+}
+/**
+ * Extract `@name` tokens from a message body — leading or inline. A token is an
+ * `@` at a WORD BOUNDARY (start of body, or after whitespace or an opening
+ * bracket/quote) followed by a name run. Quote the `@` for a multi-word display
+ * name: `@"Jacob Posel"`. Pure → unit-testable.
+ *
+ *   'hi @Izzy please look'  → ["Izzy"]
+ *   '@"Jacob Posel" ping'   → ["Jacob Posel"]
+ *   'email a@b.com'         → []          (not a word boundary)
+ *   'cost is @ the top'     → []          (bare @)
+ *   '@izzy and @Izzy'       → ["izzy"]    (deduped case-insensitively)
+ *
+ * Trailing punctuation is trimmed ("@Izzy," → "Izzy"), so a name is never
+ * polluted by the sentence around it.
+ */
+export function parseMentionTokens(body) {
+    const pattern = /(^|[\s([{<])@(?:"([^"\n]{1,80})"|([A-Za-z0-9][A-Za-z0-9._-]*))/g;
+    const names = [];
+    const seen = new Set();
+    let match;
+    while ((match = pattern.exec(body)) !== null) {
+        const raw = match[2] ?? match[3] ?? "";
+        // Only a bare name run can pick up sentence punctuation; a quoted name is
+        // taken exactly as written.
+        const name = (match[2] !== undefined ? raw : raw.replace(/[._-]+$/, "")).trim();
+        if (!name)
+            continue;
+        const key = name.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        names.push(name);
+    }
+    return names;
+}
+/**
+ * The names one roster row answers to, lowercased: its display name, the slug of
+ * that display name, any server-supplied slug/handle, the email local part, and
+ * the first word of a multi-word display name (so `@Izzy` reaches "Izzy
+ * Rivera"). A key shared by two rows makes the token AMBIGUOUS, which fails the
+ * send — never a silent pick. Pure → unit-testable.
+ */
+export function memberMatchKeys(member) {
+    const keys = new Set();
+    const add = (value) => {
+        const v = (value ?? "").trim().toLowerCase();
+        if (v)
+            keys.add(v);
+    };
+    const displayName = (member.displayName ?? "").trim();
+    add(displayName);
+    add(channelSlug(displayName));
+    add(member.slug);
+    add(member.handle);
+    add((member.email ?? "").split("@")[0]);
+    const firstWord = displayName.split(/\s+/)[0];
+    if (firstWord && firstWord !== displayName) {
+        add(firstWord);
+        add(channelSlug(firstWord));
+    }
+    return [...keys];
+}
+/**
+ * Resolve `@name` tokens against the channel roster into the structured
+ * `mentions` array. Case-insensitive on display name and slug/handle. Anything
+ * ambiguous (several roster rows answer to the name) or unresolvable (none do)
+ * FAILS with a message naming the candidates or the roster — the caller must
+ * never post a message whose "@" text mentions nobody. Pure → unit-testable.
+ */
+export function resolveMentions(tokens, members) {
+    if (tokens.length === 0)
+        return { ok: true, mentions: [] };
+    const byKey = new Map();
+    for (const member of members) {
+        if (!member.personUid)
+            continue;
+        for (const key of memberMatchKeys(member)) {
+            const bucket = byKey.get(key);
+            if (bucket)
+                bucket.push(member);
+            else
+                byKey.set(key, [member]);
+        }
+    }
+    const rosterNames = members
+        .map((m) => (m.displayName ?? "").trim() || m.personUid)
+        .filter(Boolean)
+        .sort((a, b) => a.localeCompare(b));
+    const mentions = [];
+    const claimed = new Set();
+    for (const token of tokens) {
+        const matches = byKey.get(token.trim().toLowerCase()) ?? [];
+        const unique = [...new Map(matches.map((m) => [m.personUid, m])).values()];
+        if (unique.length === 0) {
+            return {
+                ok: false,
+                error: `No channel member matches '@${token}'. Members: ` +
+                    `${rosterNames.join(", ") || "(none)"}. ` +
+                    `Fix the name, or pass --no-mentions to post the text literally.`,
+            };
+        }
+        if (unique.length > 1) {
+            const candidates = unique
+                .map((m) => `${(m.displayName ?? "").trim() || m.personUid} (${m.personUid})`)
+                .join(", ");
+            return {
+                ok: false,
+                error: `'@${token}' is ambiguous — it matches ${unique.length} members: ${candidates}. ` +
+                    `Use the full name in quotes (e.g. @"Full Name"), or pass --no-mentions ` +
+                    `to post the text literally.`,
+            };
+        }
+        const member = unique[0];
+        if (claimed.has(member.personUid))
+            continue;
+        claimed.add(member.personUid);
+        mentions.push({
+            participantUid: member.personUid,
+            participantType: mentionParticipantType(member.personUid),
+            displayName: (member.displayName ?? "").trim() || member.personUid,
+        });
+    }
+    if (mentions.length > MAX_CHANNEL_MENTIONS) {
+        return {
+            ok: false,
+            error: `That message mentions ${mentions.length} members; the server accepts at most ` +
+                `${MAX_CHANNEL_MENTIONS}. Trim the mentions, or pass --no-mentions.`,
+        };
+    }
+    return { ok: true, mentions };
+}
 /**
  * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
  * Returns null on anything that doesn't match. Pure → unit-testable.
@@ -336,6 +487,23 @@ async function fetchChannels(token) {
     const data = (await res.json());
     return data.channels ?? [];
 }
+/**
+ * Fetch a channel's roster (GET /v1/notify/channels/{id}/members). Any member
+ * who can read the channel may read its members, so this is the same gate the
+ * post itself passes. Used to resolve `@name` mentions into participant uids.
+ */
+async function fetchChannelMembers(token, channelId) {
+    const res = await vaultApiFetch({
+        token,
+        path: `/v1/notify/channels/${encodeURIComponent(channelId)}/members`,
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        throw new Error(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText));
+    }
+    const data = (await res.json());
+    return data.members ?? [];
+}
 /**
  * Channel DM path: `hq dm vyg-dev "msg"`, `hq dm '#vyg-dev' "msg"`, or
  * `hq dm --channel vyg-dev "msg"`. Resolves the caller's channel by name via
@@ -373,18 +541,38 @@ async function runChannelSend(channelName, message, opts) {
             process.exit(1);
         }
         const channel = matches[0];
+        // Mentions are structured-only server-side: resolve `@name` against the
+        // roster and send the array, or fail before posting. --no-mentions opts out
+        // and posts the text literally.
+        let mentions = [];
+        if (opts.mentions !== false) {
+            const tokens = parseMentionTokens(body);
+            if (tokens.length > 0) {
+                const members = await fetchChannelMembers(token, channel.channelId);
+                const resolved = resolveMentions(tokens, members);
+                if (!resolved.ok) {
+                    console.error(chalk.red(resolved.error));
+                    process.exit(1);
+                    return;
+                }
+                mentions = resolved.mentions;
+            }
+        }
         const sendRes = await vaultApiFetch({
             token,
             path: `/v1/notify/channels/${encodeURIComponent(channel.channelId)}/messages`,
             method: "POST",
-            body: { body },
+            body: mentions.length > 0 ? { body, mentions } : { body },
         });
         if (!sendRes.ok) {
             const err = (await sendRes.json().catch(() => ({})));
             console.error(chalk.red(friendlyDmError(sendRes.status, err.code, err.error ?? err.message ?? sendRes.statusText)));
             process.exit(1);
         }
-        console.log(chalk.green(`Message posted to #${channel.name ?? channelName}.`));
+        const mentionSuffix = mentions.length > 0
+            ? ` Mentioned ${mentions.map((m) => m.displayName).join(", ")}.`
+            : "";
+        console.log(chalk.green(`Message posted to #${channel.name ?? channelName}.${mentionSuffix}`));
     }
     catch (err) {
         console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -781,8 +969,9 @@ export function registerDmCommand(program) {
         .description("Send and read direct messages, and manage connection requests.");
     dm
         .command("send [recipient] [message]", { isDefault: true, hidden: true })
-        .description('Send a direct message. RECIPIENT can be a person (email, personUid, or agentUid), a GROUP DM (comma-separated: "a@x.com,b@y.com"), or one of your DM CHANNELS by name — bare (hq dm vyg-dev "hi"), hash form (hq dm "#vyg-dev" "hi"), or via --channel (hq dm --channel vyg-dev "hi"). A person receives a DM as an HQ Sync notification; an agent receives it in its durable box inbox. If you aren\'t connected yet, it sends a connection request that holds your message. See your channels with `hq channels`.')
+        .description('Send a direct message. RECIPIENT can be a person (email, personUid, or agentUid), a GROUP DM (comma-separated: "a@x.com,b@y.com"), or one of your DM CHANNELS by name — bare (hq dm vyg-dev "hi"), hash form (hq dm "#vyg-dev" "hi"), or via --channel (hq dm --channel vyg-dev "hi"). A person receives a DM as an HQ Sync notification; an agent receives it in its durable box inbox. If you aren\'t connected yet, it sends a connection request that holds your message. See your channels with `hq channels`.\n\nCHANNEL MENTIONS: HQ mentions are structured — the server never reads `@name` out of your text, so a channel message has to carry the participants alongside the body. When you write `@name` in a channel message, this command looks the name up in the channel roster (case-insensitive on display name and slug/handle; quote multi-word names as @"Jacob Posel") and sends it as a real mention, which notifies people and wakes agents. If a name is unknown or matches more than one member, the send FAILS with the candidates instead of posting something that mentions nobody. A bare "@" or an email address in your prose is never treated as a mention. Pass --no-mentions to post the text literally.')
         .option("--channel <name>", "Post the message to one of your DM channels by name (e.g. --channel vyg-dev)")
+        .option("--no-mentions", "Do not resolve `@name` in a channel message into structured mentions — post the text literally")
         .option("--prompt <text>", "Agent-context prompt the recipient can one-click copy into their agent (1:1 DMs only)")
         .option("--prompt-file <path>", "Read the agent prompt from a file (1:1 DMs only)")
         .option("--details <text>", "Longer detail shown in the recipient's DM detail window (1:1 DMs only)")

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/client-health-contract.d.ts

@@ -128,8 +128,17 @@ export interface ClientHealthHeartbeat {
     syncState: ClientHealthSyncState;
     /** Last time a sync RUN started — distinct from success. */
     lastSyncAttemptAt?: string;
-    /** Advances only on genuine success (including no-change runs). */
+    /** Advances only on a genuine COMPLETED run (including no-change runs). Never the engine watermark. */
     lastSyncSuccessAt?: string;
+    /**
+     * Sync-engine per-file journal high-water mark (hq-cloud `journal.lastSync`).
+     * Advances whenever ANY file moves — including on a run that later FAILS —
+     * so it is NOT proof a run completed and must never be read as a completed
+     * success. Distinct from `lastSyncSuccessAt`, and never folded into it.
+     * Absent on clients with no local sync engine (desktop) and on clients that
+     * predate this field — absence means "unknown", not "no activity".
+     */
+    syncEngineWatermarkAt?: string;
     consecutiveFailures: number;
     conflictCount?: number;
     updaterState?: ClientHealthUpdaterState;

package/dist/utils/client-health-contract.js

@@ -253,6 +253,8 @@ export function parseClientHealthHeartbeat(input) {
         heartbeat.lastSyncAttemptAt = assertIsoUtc("lastSyncAttemptAt", raw.lastSyncAttemptAt);
     if (raw.lastSyncSuccessAt !== undefined)
         heartbeat.lastSyncSuccessAt = assertIsoUtc("lastSyncSuccessAt", raw.lastSyncSuccessAt);
+    if (raw.syncEngineWatermarkAt !== undefined)
+        heartbeat.syncEngineWatermarkAt = assertIsoUtc("syncEngineWatermarkAt", raw.syncEngineWatermarkAt);
     if (raw.conflictCount !== undefined) {
         heartbeat.conflictCount = assertBoundedInt("conflictCount", raw.conflictCount, CLIENT_HEALTH_MAX_CONFLICT_COUNT);
     }

package/dist/utils/client-health.js

@@ -335,7 +335,13 @@ export function buildCliHeartbeat(input) {
     if (input.versions.sync && SEMVER.test(input.versions.sync)) {
         versions.desktop = input.versions.sync;
     }
-    const lastSyncSuccessAt = latestIso(input.state.lastSyncSuccessAt, input.journalLastSyncAt);
+    // `lastSyncSuccessAt` is ONLY this CLI's own completed-run success — never
+    // the engine journal watermark. The watermark is carried on its own field
+    // (`syncEngineWatermarkAt`) so support can tell a completed run from mere
+    // per-file engine movement; folding the two would fabricate a completed-run
+    // success out of a run that may have failed (US-019).
+    const lastSyncSuccessAt = input.state.lastSyncSuccessAt ?? null;
+    const syncEngineWatermarkAt = input.journalLastSyncAt;
     let syncState;
     switch (input.kind) {
         case "sync_attempt":
@@ -351,17 +357,20 @@ export function buildCliHeartbeat(input) {
             // overwrote the `error` state the failing sync had reported while
             // leaving the streak that earned it untouched.
             //
-            // Only this CLI's own `sync_success` clears the streak. The journal
-            // `lastSync` folded into `lastSyncSuccessAt` below deliberately does
-            // NOT: the engine stamps it per FILE update (hq-cloud journal.ts
-            // `updateEntry`), and a push stamps it before throwing its upload worker
-            // errors — so it means "some file moved", not "a run succeeded", and
-            // must never clear an alarm counter. That is why this branch keys off
-            // the streak rather than off the success timestamp.
+            // Only this CLI's own `sync_success` clears the streak. The engine
+            // journal watermark (`syncEngineWatermarkAt`) deliberately does NOT: the
+            // engine stamps it per FILE update (hq-cloud journal.ts `updateEntry`),
+            // and a push stamps it before throwing its upload worker errors — so it
+            // means "some file moved", not "a run succeeded", and must never clear an
+            // alarm counter. `never_synced` still keys off ANY observed sync activity
+            // (a completed run OR engine movement); it only means this installation
+            // has never moved a byte.
             if (input.state.consecutiveFailures > 0)
                 syncState = "error";
-            else
-                syncState = lastSyncSuccessAt ? "idle" : "never_synced";
+            else {
+                const hasSyncedSomething = lastSyncSuccessAt !== null || syncEngineWatermarkAt !== null;
+                syncState = hasSyncedSomething ? "idle" : "never_synced";
+            }
             break;
     }
     const heartbeat = {
@@ -382,20 +391,15 @@ export function buildCliHeartbeat(input) {
     if (lastSyncSuccessAt !== null) {
         heartbeat.lastSyncSuccessAt = lastSyncSuccessAt;
     }
+    if (syncEngineWatermarkAt !== null) {
+        heartbeat.syncEngineWatermarkAt = syncEngineWatermarkAt;
+    }
     if ((input.kind === "sync_success" || input.kind === "sync_failure") &&
         input.localFilesOverview) {
         heartbeat.localFilesOverview = input.localFilesOverview;
     }
     return heartbeat;
 }
-function latestIso(a, b) {
-    const times = [a, b]
-        .map((value) => (typeof value === "string" ? Date.parse(value) : NaN))
-        .filter((value) => Number.isFinite(value));
-    if (times.length === 0)
-        return null;
-    return new Date(Math.max(...times)).toISOString();
-}
 const defaultPoster = (heartbeat, token, signal) => vaultApiFetch({
     token,
     path: "/v1/client-health/heartbeat",

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