@indigoai-us/hq-cli 5.108.11 → 5.108.13

package/CHANGELOG.md

@@ -2,8 +2,56 @@
 
 ## [Unreleased]
 
+## [5.108.13] — 2026-09-06
+
+## [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/commands/skill.d.ts

@@ -52,14 +52,30 @@ export declare function mapSkillError(status: number, body: Record<string, unkno
  *   403, 404, 409, 429  -> ExpectedUserError (HQ-CLI-6: printed, exit 1, not captured)
  *   everything else     -> unmarked Error    (still captured to Sentry)
  *
- * The 4xx allowlist is closed and ENUMERATED, not a `status < 500` range: a 400
- * or 422 means the CLI itself built a malformed request, and every 5xx is a real
- * server fault — both must keep reaching Sentry so a genuine defect is never
- * hidden behind a "caller error" label (HQ-CLI-Z, Sentry 7694457056). Before
- * this, both call sites threw a bare `new Error(...)`, so a correctly-denied 403
- * (e.g. an agent principal with no person entity) fell through the boundary's
- * closed allowlist and filed a crash report for what hq-pro itself deliberately
- * exempts from Sentry capture.
+ * The 4xx allowlist is closed and ENUMERATED, not a `status < 500` range, and
+ * every 5xx is a real server fault that must keep reaching Sentry so a genuine
+ * defect is never hidden behind a "caller error" label (HQ-CLI-Z, Sentry
+ * 7694457056). Before this, both call sites threw a bare `new Error(...)`, so a
+ * correctly-denied 403 (e.g. an agent principal with no person entity) fell
+ * through the boundary's closed allowlist and filed a crash for what hq-pro
+ * itself deliberately exempts from Sentry capture.
+ *
+ * A 400 is DISCRIMINATED BY ITS MACHINE-READABLE `code`, never by status alone
+ * and never by the prose (Sentry 7710011866). On the register route the
+ * observed 400s reject the CALLER'S OWN SKILL.md CONTENT
+ * (`SKILL_REGISTER_FRONTMATTER_INVALID`, `SKILL_REGISTER_TOO_LARGE`, …) — the
+ * caller fixes the file and retries; there is no hq-cli defect and no operator
+ * action — and hq-pro returns each of those through its NON-capturing
+ * `expectedValidationResponse` builder, so hq-cli was the only party filing a
+ * crash for them. Those codes (see `CALLER_CONTENT_REGISTER_400_CODES`) are
+ * marked `expected`. A 400 whose `code` is absent, non-string, or unlisted —
+ * including `SKILL_REGISTER_PATH_INVALID`, the ONE register field hq-cli builds
+ * itself (`path: skills/<slug>/SKILL.md`) — stays an unmarked, captured Error,
+ * as does every 422: an envelope the CLI built wrong is a genuine hq-cli defect.
+ * Client-side suppression cannot blind a real fault: hq-pro retains its
+ * capturing `response()` builder for every register 400 it still considers a
+ * fault, so this only stops hq-cli from double-filing what the server already
+ * exempts.
  *
  * `opts.machineIdentity` distinguishes a company agent (`isMachineIdentity()`).
  * A machine session mints automatically and is never repaired by `hq login`, so

package/dist/commands/skill.js

@@ -18,6 +18,7 @@ import { vaultApiFetch } from "../utils/vault-api.js";
 import { surfaceCompanySkill } from "../lib/company-skill-wrapper.js";
 import { AuthError } from "../utils/auth-error.js";
 import { redactErrorText } from "../utils/redact-error-text.js";
+import { stampVaultAccessDenied, vaultAccessDeniedDiagnostics, } from "../utils/vault-access-denied-error.js";
 export const SKILL_UID_PATTERN = /^skl_[A-Za-z0-9]+$/;
 export const SKILL_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const COMPANY_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
@@ -208,6 +209,36 @@ export function mapSkillError(status, body) {
         return `Server error: ${server || status}`;
     return server || `Request failed (${status})`;
 }
+/**
+ * The CLOSED, ENUMERATED set of skills-API register `code` values whose 400
+ * refuses the CALLER-AUTHORED SKILL.md CONTENT rather than the CLI-built request
+ * envelope. hq-pro returns each of these through its NON-capturing
+ * `expectedValidationResponse` builder (hq-pro src/vault-service/write-routes.ts)
+ * — a deliberate, correctly-handled client 400 where the caller fixes the file
+ * and retries and there is no operator action:
+ *
+ *   SKILL_REGISTER_FRONTMATTER_INVALID  `SKILL.md must contain valid YAML frontmatter`
+ *   SKILL_REGISTER_TOO_LARGE            `Skill content exceeds <N> bytes`
+ *   SKILL_REGISTER_CONTENT_INVALID      malformed skill body / structure
+ *   SKILL_REGISTER_METADATA_INVALID     bad frontmatter metadata (e.g. description)
+ *   SKILL_REGISTER_GOVERNANCE_INVALID   `normalizeSkillTags` rejected the caller's tags
+ *
+ * DELIBERATELY EXCLUDES `SKILL_REGISTER_PATH_INVALID`: the `path` field is built
+ * by hq-cli (`skills/${slug}/SKILL.md`), so a rejection there is a genuine
+ * hq-cli defect and must keep reaching Sentry. The two evidenced codes are the
+ * first two; the rest are the register route's other caller-content validators,
+ * covered so a content refusal never files a crash. Client suppression is safe
+ * either way — hq-pro still captures every register 400 it classifies as a
+ * fault through its own `response()` builder, so narrowing this set to the two
+ * evidenced codes would only re-expose siblings the server already exempts.
+ */
+const CALLER_CONTENT_REGISTER_400_CODES = new Set([
+    "SKILL_REGISTER_FRONTMATTER_INVALID",
+    "SKILL_REGISTER_TOO_LARGE",
+    "SKILL_REGISTER_CONTENT_INVALID",
+    "SKILL_REGISTER_METADATA_INVALID",
+    "SKILL_REGISTER_GOVERNANCE_INVALID",
+]);
 /**
  * Type a failed skills-API response by its HTTP status so the top-level error
  * boundary can tell a correctly-denied client 4xx (ordinary caller state) from a
@@ -220,14 +251,30 @@ export function mapSkillError(status, body) {
  *   403, 404, 409, 429  -> ExpectedUserError (HQ-CLI-6: printed, exit 1, not captured)
  *   everything else     -> unmarked Error    (still captured to Sentry)
  *
- * The 4xx allowlist is closed and ENUMERATED, not a `status < 500` range: a 400
- * or 422 means the CLI itself built a malformed request, and every 5xx is a real
- * server fault — both must keep reaching Sentry so a genuine defect is never
- * hidden behind a "caller error" label (HQ-CLI-Z, Sentry 7694457056). Before
- * this, both call sites threw a bare `new Error(...)`, so a correctly-denied 403
- * (e.g. an agent principal with no person entity) fell through the boundary's
- * closed allowlist and filed a crash report for what hq-pro itself deliberately
- * exempts from Sentry capture.
+ * The 4xx allowlist is closed and ENUMERATED, not a `status < 500` range, and
+ * every 5xx is a real server fault that must keep reaching Sentry so a genuine
+ * defect is never hidden behind a "caller error" label (HQ-CLI-Z, Sentry
+ * 7694457056). Before this, both call sites threw a bare `new Error(...)`, so a
+ * correctly-denied 403 (e.g. an agent principal with no person entity) fell
+ * through the boundary's closed allowlist and filed a crash for what hq-pro
+ * itself deliberately exempts from Sentry capture.
+ *
+ * A 400 is DISCRIMINATED BY ITS MACHINE-READABLE `code`, never by status alone
+ * and never by the prose (Sentry 7710011866). On the register route the
+ * observed 400s reject the CALLER'S OWN SKILL.md CONTENT
+ * (`SKILL_REGISTER_FRONTMATTER_INVALID`, `SKILL_REGISTER_TOO_LARGE`, …) — the
+ * caller fixes the file and retries; there is no hq-cli defect and no operator
+ * action — and hq-pro returns each of those through its NON-capturing
+ * `expectedValidationResponse` builder, so hq-cli was the only party filing a
+ * crash for them. Those codes (see `CALLER_CONTENT_REGISTER_400_CODES`) are
+ * marked `expected`. A 400 whose `code` is absent, non-string, or unlisted —
+ * including `SKILL_REGISTER_PATH_INVALID`, the ONE register field hq-cli builds
+ * itself (`path: skills/<slug>/SKILL.md`) — stays an unmarked, captured Error,
+ * as does every 422: an envelope the CLI built wrong is a genuine hq-cli defect.
+ * Client-side suppression cannot blind a real fault: hq-pro retains its
+ * capturing `response()` builder for every register 400 it still considers a
+ * fault, so this only stops hq-cli from double-filing what the server already
+ * exempts.
  *
  * `opts.machineIdentity` distinguishes a company agent (`isMachineIdentity()`).
  * A machine session mints automatically and is never repaired by `hq login`, so
@@ -255,6 +302,19 @@ export function skillApiError(status, body, opts = {}) {
     if (status === 401) {
         return opts.machineIdentity ? new Error(message) : new AuthError(message);
     }
+    if (status === 400 &&
+        typeof body.code === "string" &&
+        CALLER_CONTENT_REGISTER_400_CODES.has(body.code)) {
+        // A register 400 refusing the caller's own SKILL.md content — expected
+        // caller state hq-pro itself does not capture (see the code allowlist
+        // above). The message is the UNCHANGED `redactErrorText(mapSkillError(...))`
+        // remedy; only the class changes. A 400 with an absent, non-string, or
+        // unlisted `code` (including the CLI-built `SKILL_REGISTER_PATH_INVALID`)
+        // falls through to the unmarked, captured Error below.
+        return Object.assign(new Error(message), {
+            expected: true,
+        });
+    }
     if (status === 403 || status === 404 || status === 409 || status === 429) {
         return Object.assign(new Error(message), {
             expected: true,
@@ -387,6 +447,23 @@ export function registerSkillCommand(program, deps = {}) {
                 // sync failure exactly as it does everywhere else, and a genuine
                 // fault is captured under its own type and stack.
                 console.warn(chalk.yellow(`⚠ Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync failed.`));
+                // ARM B (Sentry 7709408531): when the upload was DENIED by S3 (an
+                // AWS SDK v3 403 from a truncated IAM session policy that dropped the
+                // skills/ prefix), stamp bounded, hq-derived diagnostics onto the
+                // ORIGINAL error so the boundary can print an attributable remedy and
+                // capture WITH a bounded context. This is additive only: a
+                // non-enumerable field, no new Error, no change to `message`/`name`/
+                // `cause` — rewrapping is the exact HQ-CLI-14 defect this block
+                // prevents. A non-403 sync failure is left untouched and captures (or
+                // is suppressed) under its own type exactly as before.
+                if (err && typeof err === "object") {
+                    const diagnostics = vaultAccessDeniedDiagnostics(err, {
+                        companySlug,
+                        objectKey: `skills/${slug}/SKILL.md`,
+                    });
+                    if (diagnostics)
+                        stampVaultAccessDenied(err, diagnostics);
+                }
                 throw err;
             }
             if (syncResult.aborted) {

package/dist/main.js

@@ -45,6 +45,7 @@ import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
 import { kickFlagRegistryReadiness } from "./lib/flag-registry.js";
 import { isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
+import { isVaultAccessDeniedError, vaultAccessDeniedMessage, } from "./utils/vault-access-denied-error.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
 /** Hard upper bound for non-user-visible release-health finalization. */
 const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
@@ -335,6 +336,27 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         });
         deps.setExitCode(1);
     }
+    else if (isVaultAccessDeniedError(err)) {
+        // ARM B (Sentry 7709408531): `hq skill create`'s post-register vault sync
+        // was DENIED by S3 — an AWS SDK v3 403 from an hq-pro IAM session-policy
+        // truncation that dropped the skills/ prefix. Because the HEAD carried no
+        // body, the SDK minted an untyped `Unknown http=403 UnknownError` with a
+        // system-only stack, so it reached the final else, printed
+        // `hq: Unknown: Unknown http=403 UnknownError`, and captured an
+        // un-attributable event. skill.ts stamped bounded, hq-derived diagnostics
+        // onto the error at the failure site; print the attributable remedy naming
+        // the object and company, and STILL capture WITH that bounded context —
+        // this is a real hq-pro platform fault that must stay REPORTED and become
+        // actionable, never silenced. Mirrors the package-root branch's
+        // print-and-capture shape. Keyed on hq-cli's own stamped field, so it is
+        // disjoint from every neighbour and changes no existing ordering.
+        const { vaultAccessDenied } = err;
+        deps.stderr.write(`hq: ${vaultAccessDeniedMessage(vaultAccessDenied)}\n`);
+        deps.sentry.captureException(err, {
+            contexts: { vault_access_denied: vaultAccessDenied },
+        });
+        deps.setExitCode(1);
+    }
     else {
         // A full disk / exhausted quota / read-only filesystem is the user's
         // machine, not an HQ code defect. Surface a clear, actionable message and

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/vault-access-denied-error.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The finite, hq-derived diagnostics for a denied vault object write. A `type`
+ * (not an `interface`) so it carries the implicit index signature Sentry's
+ * `Contexts` requires, exactly as `PackageRootResolutionDiagnostics` does.
+ */
+export type VaultAccessDeniedDiagnostics = {
+    /** The only operation that stamps this today; a closed literal, not free text. */
+    operation: "skill-sync";
+    /** hq-derived, already `COMPANY_SLUG_PATTERN`-validated at the call site. */
+    companySlug: string;
+    /** hq-built vault key (`skills/<slug>/SKILL.md`); slug is pattern-validated. */
+    objectKey: string;
+    /** Always 403 here; kept explicit so the context self-describes. */
+    httpStatusCode: number;
+    /** AWS request correlation id (`$metadata.requestId`), or null when absent. */
+    requestId: string | null;
+    /** AWS extended request id (`$metadata.extendedRequestId`), or null. */
+    extendedRequestId: string | null;
+};
+/** The hq-derived context the sync failure site already holds. */
+export interface VaultAccessDeniedHint {
+    companySlug: string;
+    objectKey: string;
+}
+/**
+ * If `err` is an AWS SDK v3 authorization failure — an object whose
+ * `$metadata.httpStatusCode` is 403 — return bounded diagnostics built from the
+ * hq-derived `hint` plus the AWS-minted request identifiers; otherwise `null`.
+ *
+ * A null result means "not an S3 403" and the caller must leave the error
+ * un-stamped so it captures under its own type, exactly as today.
+ */
+export declare function vaultAccessDeniedDiagnostics(err: unknown, hint: VaultAccessDeniedHint): VaultAccessDeniedDiagnostics | null;
+/**
+ * Stamp bounded diagnostics onto the ORIGINAL sync error as a NON-ENUMERABLE
+ * field, preserving the error's identity, `name`, `message` and `cause`
+ * (HQ-CLI-14 forbids rewrapping). Non-enumerable so the field never widens the
+ * error's own serialization, a `JSON.stringify`, or Sentry's default capture.
+ */
+export declare function stampVaultAccessDenied(err: object, diagnostics: VaultAccessDeniedDiagnostics): void;
+/** The carrier the top-level boundary matches: an error hq stamped itself. */
+export interface VaultAccessDeniedError {
+    vaultAccessDenied: VaultAccessDeniedDiagnostics;
+}
+/**
+ * True when `err` carries the diagnostics {@link stampVaultAccessDenied} put
+ * there. Keyed on hq-cli's OWN stamped field (not on `$metadata`), so the
+ * boundary branch is disjoint from every neighbour and an AWS 403 that reached
+ * the boundary by some other path — un-stamped — still captures bare.
+ */
+export declare function isVaultAccessDeniedError(err: unknown): err is VaultAccessDeniedError;
+/**
+ * One fixed-shape, input-free actionable line: it names the denied vault object
+ * and company, states that the local stamp succeeded, and gives the remedy
+ * (grants + re-run). Built only from hq-derived, pattern-validated fields, so —
+ * like `syncStateLockMessage` — it needs no redaction or length cap.
+ */
+export declare function vaultAccessDeniedMessage(diagnostics: VaultAccessDeniedDiagnostics): string;
+//# sourceMappingURL=vault-access-denied-error.d.ts.map

package/dist/utils/vault-access-denied-error.js

@@ -0,0 +1,122 @@
+// src/utils/vault-access-denied-error.ts
+//
+// Recognise — and make ATTRIBUTABLE — an AWS S3 AUTHORIZATION failure raised
+// inside `hq skill create`'s post-register vault sync. Sibling in spirit to
+// `sync-state-lock-error.ts` (HQ-CLI-14) and `package-root-diagnostics.ts`: a
+// structurally-matched carrier plus a bounded, hq-derived diagnostics payload.
+//
+// UNLIKE the suppression siblings, this class stays CAPTURED. The reported
+// event (Sentry 7709408531) is a REAL platform fault: hq-pro's STS vendor
+// TRUNCATED the IAM session policy and dropped the very `skills/` prefix being
+// written, so S3 answered the sync HEAD with 403. Because a HEAD carries no
+// body, the AWS SDK v3 could not parse an XML error code and minted an untyped
+// `Unknown http=403 UnknownError` whose `$metadata.httpStatusCode` is 403 and
+// whose stack is system-only. That reached the top-level boundary's final else,
+// which printed `hq: Unknown: Unknown http=403 UnknownError` and captured an
+// event carrying nothing that identifies the object, the company, or the
+// truncation. This module does NOT silence the 403 — it keeps it reported while
+// giving the user an actionable line and the tracker a bounded context.
+//
+// Two hard rules, mirroring the diagnostics siblings:
+//   1. STRUCTURAL match, never `instanceof`. The carrier is whatever the AWS SDK
+//      threw; the only signal read is `$metadata.httpStatusCode === 403`, so a
+//      future SDK rename cannot break it. A miss degrades to today's behaviour
+//      (still captured, just uncontextualised) — it can never suppress.
+//   2. NO caller free text, NO secrets. The company slug and object key are
+//      hq-DERIVED (both are already pattern-validated upstream); the AWS request
+//      identifiers are opaque correlation tokens, length-bounded here. STS
+//      credentials, presigned URLs and message prose never enter the payload.
+/** The non-enumerable field name the sync catch stamps and the boundary reads. */
+const VAULT_ACCESS_DENIED_FIELD = "vaultAccessDenied";
+/** Upper bound on an AWS request identifier before it enters a Sentry context. */
+const REQUEST_ID_MAX_LENGTH = 256;
+/** An AWS request identifier, coerced to a bounded string or null. */
+function boundedRequestId(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    return value.slice(0, REQUEST_ID_MAX_LENGTH);
+}
+/**
+ * If `err` is an AWS SDK v3 authorization failure — an object whose
+ * `$metadata.httpStatusCode` is 403 — return bounded diagnostics built from the
+ * hq-derived `hint` plus the AWS-minted request identifiers; otherwise `null`.
+ *
+ * A null result means "not an S3 403" and the caller must leave the error
+ * un-stamped so it captures under its own type, exactly as today.
+ */
+export function vaultAccessDeniedDiagnostics(err, hint) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const metadata = err.$metadata;
+    if (metadata === null || typeof metadata !== "object")
+        return null;
+    if (metadata.httpStatusCode !== 403) {
+        return null;
+    }
+    return {
+        operation: "skill-sync",
+        companySlug: hint.companySlug,
+        objectKey: hint.objectKey,
+        httpStatusCode: 403,
+        requestId: boundedRequestId(metadata.requestId),
+        extendedRequestId: boundedRequestId(metadata.extendedRequestId),
+    };
+}
+/** True only for a diagnostics object of the exact closed shape. */
+function isVaultAccessDeniedDiagnostics(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const d = value;
+    return (d.operation === "skill-sync" &&
+        typeof d.companySlug === "string" &&
+        typeof d.objectKey === "string" &&
+        d.httpStatusCode === 403);
+}
+/**
+ * Stamp bounded diagnostics onto the ORIGINAL sync error as a NON-ENUMERABLE
+ * field, preserving the error's identity, `name`, `message` and `cause`
+ * (HQ-CLI-14 forbids rewrapping). Non-enumerable so the field never widens the
+ * error's own serialization, a `JSON.stringify`, or Sentry's default capture.
+ */
+export function stampVaultAccessDenied(err, diagnostics) {
+    Object.defineProperty(err, VAULT_ACCESS_DENIED_FIELD, {
+        value: diagnostics,
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
+}
+/**
+ * True when `err` carries the diagnostics {@link stampVaultAccessDenied} put
+ * there. Keyed on hq-cli's OWN stamped field (not on `$metadata`), so the
+ * boundary branch is disjoint from every neighbour and an AWS 403 that reached
+ * the boundary by some other path — un-stamped — still captures bare.
+ */
+export function isVaultAccessDeniedError(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    return isVaultAccessDeniedDiagnostics(err.vaultAccessDenied);
+}
+/** Recover the create `<slug>` from an hq-built `skills/<slug>/SKILL.md` key. */
+function slugFromObjectKey(objectKey) {
+    const match = /^skills\/([a-z0-9][a-z0-9-]*)\/SKILL\.md$/.exec(objectKey);
+    return match ? match[1] : null;
+}
+/**
+ * One fixed-shape, input-free actionable line: it names the denied vault object
+ * and company, states that the local stamp succeeded, and gives the remedy
+ * (grants + re-run). Built only from hq-derived, pattern-validated fields, so —
+ * like `syncStateLockMessage` — it needs no redaction or length cap.
+ */
+export function vaultAccessDeniedMessage(diagnostics) {
+    const slug = slugFromObjectKey(diagnostics.objectKey);
+    const reRun = slug
+        ? `hq skill --company ${diagnostics.companySlug} create ${slug}`
+        : `hq skill --company ${diagnostics.companySlug} create <slug>`;
+    return (`The skill was stamped locally, but the vault upload of ` +
+        `'${diagnostics.objectKey}' was denied (HTTP 403) for company ` +
+        `'${diagnostics.companySlug}'. Your file grants don't cover that path. Ask ` +
+        `a ${diagnostics.companySlug} owner to confirm your file grants cover the ` +
+        `skills/ prefix, then re-run \`${reRun}\`.`);
+}
+//# sourceMappingURL=vault-access-denied-error.js.map

package/package.json

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