@indigoai-us/hq-cli 5.108.12 → 5.108.13

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.108.13] — 2026-09-06
+
 ## [5.108.12] - 2026-09-05
 
 ### Fixed

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