@indigoai-us/hq-cli 5.108.11 → 5.108.12

package/CHANGELOG.md

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

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/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/package.json

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