@indigoai-us/hq-cli 5.108.12 → 5.108.14

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [5.108.14] — 2026-09-07
+
+### Fixed
+
+- An incomplete hq install tree no longer files an unactionable crash when hq
+  fails to load one of its OWN bundled modules in-process (HQ-CLI-1M, HQ-CLI-1N).
+  Two shapes shared one cause — hq-cli's globally installed package tree was not
+  intact at the moment a command loaded a module. In HQ-CLI-1N (`hq core
+  timeout-guard` on Windows) a partial `npm i -g` left a RELATIVE sibling
+  unwritten deep inside a bundled dependency, so Node threw
+  `MODULE_NOT_FOUND`. In HQ-CLI-1M (`hq rescue` on Linux) a concurrent global
+  install rewrote the running tree, so an ESM module that existed at resolve was
+  gone at read and Node's loader raised `ENOENT` — the loader validates
+  existence at resolve, so an ENOENT at LOAD proves the file vanished mid-run
+  rather than being merely absent. Both carried no hq-cli frames, reached the
+  top-level handler's final `else`, and produced a bare Sentry crash plus an
+  `hq:` line the operator could not act on. A new in-process classifier now
+  recognises both shapes — but ONLY when the failing file sits under the running
+  install's own `node_modules/`, the CJS shape additionally requires a relative
+  specifier, and the ESM shape additionally requires an esm-loader frame — and
+  prints an input-free reinstall remedy (run the command again first, then
+  `npm i -g @indigoai-us/hq-cli` / `pnpm add -g @indigoai-us/hq-cli`) while
+  skipping Sentry capture, the same disposition established for the qmd child in
+  HQ-CLI-Y. An hq-cli packaging fault stays reportable: a miss under the
+  package's own `dist/` or `assets/`, a bare-specifier miss (a possible
+  undeclared dependency), and an esm-loader ENOENT whose path did not survive
+  delivery are NOT suppressed — the last is captured WITH a bounded
+  `incomplete_install` context so the next occurrence is attributable. The drop
+  is wired both at the top-level boundary and in the shared `beforeSend`, so it
+  covers every capture route.
+
+## [5.108.13] — 2026-09-06
+
 ## [5.108.12] - 2026-09-05
 
 ### Fixed

package/dist/commands/agents.d.ts

@@ -110,9 +110,20 @@ export interface ProfilePatch {
     description?: string;
 }
 export interface RuntimeConfigPatch {
+    /**
+     * Brain/runtime provider. When present the server routes the PATCH to a
+     * PROVIDER MIGRATION (handleProviderMigration): it TERMINATES and reprovisions
+     * the box and changes the provider/auth contract. Omit for a plain tuning
+     * patch (model / effort / tier).
+     */
+    provider?: string;
     codexModel?: string;
     codexReasoningEffort?: string;
     codexServiceTier?: string;
+    /** Provider-migration auth mode: "subscription" | "apiKey". */
+    codexAuthMode?: string;
+    /** Provider-migration apiKey-mode vault key reference (never a raw secret). */
+    codexApiKeyRef?: string;
 }
 /**
  * Authenticated JSON round-trip against the agents control plane. Throws
@@ -143,7 +154,12 @@ export interface ProvisionAgentInput {
     /** Server quote assertion; hq-pro re-prices and refuses a stale amount. */
     quotedNetMonthlyCents?: number;
     quoteCatalogVersion?: string;
+    /** Funnel attribution: which client surface made the attempt. */
+    surface?: AgentCreateSurface;
 }
+/** Closed set shared with hq-pro's agent_create_* funnel contract. */
+export declare const CLI_AGENT_CREATE_SURFACE: "cli_agents_create";
+export type AgentCreateSurface = typeof CLI_AGENT_CREATE_SURFACE;
 export interface AgentCreateSizeOption {
     key: "basic" | "power" | "dev";
     productName: string;

package/dist/commands/agents.js

@@ -146,6 +146,8 @@ export function slugifyAgentName(name) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
 }
+/** Closed set shared with hq-pro's agent_create_* funnel contract. */
+export const CLI_AGENT_CREATE_SURFACE = "cli_agents_create";
 /** Read hq-pro's company-specific creation prices and capacities. */
 export async function getAgentCreateOptions(token, companyUid, idempotencyKey) {
     const raw = await agentsRequest({
@@ -153,7 +155,9 @@ export async function getAgentCreateOptions(token, companyUid, idempotencyKey) {
         path: "/v1/agents/provision-options",
         query: {
             companyUid,
-            ...(idempotencyKey ? { idempotencyKey } : {}),
+            ...(idempotencyKey
+                ? { idempotencyKey, surface: CLI_AGENT_CREATE_SURFACE }
+                : {}),
         },
     });
     if (!raw || typeof raw !== "object") {
@@ -842,6 +846,7 @@ export function registerAgentsCommand(program) {
                         : { desiredInstanceType: quotedSize.instanceType }),
                     quotedNetMonthlyCents: quotedSize.netMonthlyCents,
                     quoteCatalogVersion: createOptions.catalogVersion,
+                    surface: CLI_AGENT_CREATE_SURFACE,
                 });
                 const uid = typeof result.uid === "string" ? result.uid : slug;
                 console.log(chalk.green(`Provisioning started for agent "${name}".`));
@@ -999,15 +1004,54 @@ export function registerAgentsCommand(program) {
     });
     agents
         .command("config <agentUid>")
-        .description("Update an agent's runtime config (model / reasoning effort / service tier)")
+        .description("Update an agent's runtime config (model / reasoning effort / service tier), or migrate its brain/runtime provider with --provider (DESTRUCTIVE: terminates + reprovisions the box)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--model <model>", "Codex model id")
         .option("--effort <effort>", "Reasoning effort: minimal | low | medium | high | xhigh")
         .option("--tier <tier>", "Service tier (speed): default | priority")
+        .option("--provider <provider>", "Migrate brain/runtime provider (codex | grok | claude | agents-v2). DESTRUCTIVE: terminates and reprovisions the box; requires --model and --yes.")
+        .option("--auth-mode <mode>", "Provider-migration auth mode: subscription | apiKey (default: keep current)")
+        .option("--api-key-ref <ref>", "Provider-migration apiKey-mode vault key reference (never a raw key)")
+        .option("--yes", "Confirm a destructive provider migration (required with --provider)")
         .option("--json", "Emit raw JSON")
         .action(async function (agentUid, opts) {
         try {
             const patch = {};
+            if (opts.provider !== undefined) {
+                // A `provider` field routes the server to handleProviderMigration,
+                // which TERMINATES and reprovisions the box. Guard it: valid provider,
+                // an explicit target --model (the server requires it), and --yes.
+                // Reuses the module-level VALID_PROVIDERS (shared with `provision`).
+                const provider = opts.provider.trim().toLowerCase();
+                if (!VALID_PROVIDERS.has(provider)) {
+                    console.error(chalk.red(`Invalid --provider '${opts.provider}': must be one of codex, grok, claude, agents-v2`));
+                    process.exit(1);
+                }
+                if (opts.model === undefined) {
+                    console.error(chalk.red("A provider migration requires --model (the target brain's model id)."));
+                    process.exit(1);
+                }
+                if (!opts.yes) {
+                    console.error(chalk.red(`Refusing to migrate agent ${agentUid} to provider '${provider}' without --yes.\n` +
+                        "This TERMINATES and reprovisions the box (irreversible) and changes the auth contract.\n" +
+                        "Re-run with --yes once you have confirmed the exact agent, company, and model."));
+                    process.exit(1);
+                }
+                if (provider !== "agents-v2") {
+                    // v1 RESIDENT runtime guard: codex|grok|claude migrate the agent OFF
+                    // agents-v2 onto the legacy resident runtime. Fleet boxes run
+                    // agents-v2 (brain derived from the model), so this is almost always
+                    // a mistake — warn loudly but proceed (the operator passed --yes).
+                    console.warn(chalk.yellow(`Warning: --provider ${provider} targets the V1 RESIDENT runtime, not agents-v2.\n` +
+                        "Fleet boxes run agents-v2. To keep this agent on the v2 runtime with a\n" +
+                        `${provider} brain, use: --provider agents-v2 --model <${provider} model id>`));
+                }
+                patch.provider = provider;
+                if (opts.authMode !== undefined)
+                    patch.codexAuthMode = opts.authMode;
+                if (opts.apiKeyRef !== undefined)
+                    patch.codexApiKeyRef = opts.apiKeyRef;
+            }
             if (opts.model !== undefined)
                 patch.codexModel = opts.model;
             if (opts.effort !== undefined) {

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

@@ -23,6 +23,7 @@ import { qmdQueryDocumentMessage } from "./utils/qmd-query-document-error.js";
 import { qmdModelDownloadMessage } from "./utils/qmd-model-download-error.js";
 import { qmdWorkdirMissingMessage } from "./utils/qmd-workdir-missing-error.js";
 import { hqStateWriteErrorMessage } from "./utils/hq-state-write-error.js";
+import { incompleteInstallMessage, incompleteInstallCaptureContext, } from "./utils/incomplete-install-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isVarlockEnvError } from "./run/env-graph-guard.js";
 import { isEpipe } from "./utils/epipe.js";
@@ -45,6 +46,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 +337,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
@@ -493,7 +516,28 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         const stateWriteMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg
             ? null
             : hqStateWriteErrorMessage(err);
-        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg
+        // An IN-PROCESS module-load failure that means hq-cli's OWN installed
+        // package tree is incomplete at load time — a partial/interrupted global
+        // install left a bundled file unwritten (HQ-CLI-1N, a CJS relative-sibling
+        // MODULE_NOT_FOUND), or a concurrent global install rewrote the running
+        // tree so an ESM module present at resolve was gone at read (HQ-CLI-1M, an
+        // esm-loader ENOENT). Both carry no hq-cli frames and reached the final
+        // else, filing a bare crash and an unactionable line. An incomplete
+        // install is the caller's machine, the disposition HQ-CLI-Y already
+        // established for the qmd CHILD — print the input-free reinstall remedy and
+        // skip capture. Placed with the environmental family (after the typed qmd
+        // carriers and the hq state-write carrier, before environmentalFsErrorMessage):
+        // the signatures are disjoint — ENVIRONMENTAL_FS_CODES is only
+        // ENOSPC/EDQUOT/EROFS (never ENOENT/MODULE_NOT_FOUND), no qmd carrier sets
+        // requireStack or an esm-loader frame, and the classified file must sit
+        // under <packageRoot>/node_modules — so ordering changes nothing that
+        // exists. The UNATTRIBUTABLE shape (an esm-loader ENOENT whose path did not
+        // survive) is deliberately NOT suppressed; it is captured WITH bounded
+        // context on the generic path below.
+        const incompleteInstallMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg
+            ? null
+            : incompleteInstallMessage(err);
+        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg || incompleteInstallMsg
             ? null
             : environmentalFsErrorMessage(err);
         // A LOCAL sync-state lock failure (@indigoai-us/hq-cloud's
@@ -510,7 +554,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // environmental-fs check, before network-transport — is pinned by tests.
         // The `in-process-async-holder` reason is deliberately NOT suppressed here
         // (see sync-state-lock-error.ts); it stays captured.
-        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg || envMsg
+        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg || incompleteInstallMsg || envMsg
             ? null
             : syncStateLockMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
@@ -534,6 +578,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             modelDownloadMsg ||
             workdirMissingMsg ||
             stateWriteMsg ||
+            incompleteInstallMsg ||
             envMsg ||
             lockMsg
             ? null
@@ -571,6 +616,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (stateWriteMsg) {
             deps.stderr.write(`hq: ${stateWriteMsg}\n`);
         }
+        else if (incompleteInstallMsg) {
+            deps.stderr.write(`hq: ${incompleteInstallMsg}\n`);
+        }
         else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }
@@ -581,13 +629,18 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             deps.stderr.write(`hq: ${transportMsg}\n`);
         }
         else {
-            // A genuinely unclassified fault is still captured exactly once. When it
-            // is a qmd spawn-level failure the fix could not attribute, attach the
-            // bounded existence context so the next occurrence carries the evidence
-            // the reported HQ-CLI-1A event lacked; every other error captures bare.
+            // A genuinely unclassified fault is still captured exactly once. Two
+            // shapes attach bounded, hq-derived context so the next occurrence
+            // carries the evidence this one lacked: a qmd spawn-level failure the fix
+            // could not attribute (HQ-CLI-1A), and an esm-loader ENOENT whose path
+            // did not survive delivery (HQ-CLI-1M — the unattributable incomplete-
+            // install shape). Every other error captures bare, exactly as before.
             const spawnContext = qmdSpawnFailureCaptureContext(err);
-            if (spawnContext) {
-                deps.sentry.captureException(err, spawnContext);
+            const installContext = incompleteInstallCaptureContext(err);
+            if (spawnContext || installContext) {
+                deps.sentry.captureException(err, {
+                    contexts: { ...spawnContext?.contexts, ...installContext },
+                });
             }
             else {
                 deps.sentry.captureException(err);

package/dist/sentry.js

@@ -6,6 +6,7 @@ import { CLI_VERSION } from "./cli-version.js";
 import { getCachedSentryUser } from "./utils/sentry-identity.js";
 import { isEpipe } from "./utils/epipe.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { incompleteInstallMessage } from "./utils/incomplete-install-error.js";
 import { sentryFingerprintFor } from "./utils/sentry-fingerprint.js";
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
@@ -31,6 +32,20 @@ export function epipeAwareBeforeSend(event, hint) {
     // route, while the CLI still exits non-zero. HQ-CLI-R (Sentry 7671416365).
     if (environmentalFsErrorMessage(hint?.originalException))
         return null;
+    // Path-independent belt for an IN-PROCESS incomplete-install module-load
+    // failure — hq-cli's own globally installed tree is not intact at load time
+    // (HQ-CLI-1N, a CJS relative-sibling MODULE_NOT_FOUND under its bundled
+    // node_modules; HQ-CLI-1M, an esm-loader ENOENT for a file present at resolve
+    // and gone at read). handleTopLevelError already prints the reinstall remedy
+    // for the top-level route; dropping the event here suppresses the fatal
+    // regardless of route — the unhandled-rejection boundary, the command-level
+    // captureException sites, and bin/hq-auth-refresh — mirroring the EPIPE and
+    // environmental-fs drops above. The classifier reads only structured fields
+    // and the failing file must sit under the running install's node_modules, so
+    // an hq-cli packaging fault (a dist/ miss, a bare-specifier miss) and the
+    // path-less unattributable shape are NOT dropped here and stay captured.
+    if (incompleteInstallMessage(hint?.originalException))
+        return null;
     // Group an event that survives to send by a BOUNDED machine discriminator so
     // unrelated gateway/HTTP failures stop colliding into one fungible issue
     // (HQ-CLI collision, Sentry 7642756130). Placed here — path-independent,

package/dist/utils/incomplete-install-error.d.ts

@@ -0,0 +1,50 @@
+import * as fs from "fs";
+/**
+ * The actionable remedy shown to the operator. Input-free — nothing from the
+ * error, the argv, or the filesystem is interpolated — so there is no injection
+ * surface and no way to inflate Sentry grouping, matching the bounded-remedy
+ * discipline of every sibling classifier. Covers BOTH sub-cases in the order a
+ * user should try them: re-run first (an install that finished mid-run leaves
+ * the next invocation healthy), then reinstall if it persists.
+ */
+export declare const INCOMPLETE_INSTALL_REMEDY: string;
+/** A resolver for the running install's root; returns null instead of throwing. */
+export type PackageRootResolver = () => string | null;
+/**
+ * If `err` is an in-process incomplete-install module-load failure — either the
+ * CJS relative-sibling shape (HQ-CLI-1N) or the ESM vanished-file shape
+ * (HQ-CLI-1M), with the failing file confirmed under `<packageRoot>/node_modules/`
+ * — return the actionable, input-free reinstall remedy; otherwise return null.
+ *
+ * Mirrors qmdModuleMissingMessage so the top-level handler and beforeSend branch
+ * the same way: a non-null result means print-the-remedy-and-skip-Sentry, null
+ * means "handle as usual (capture to Sentry)". Never throws — a resolver that
+ * fails yields null.
+ */
+export declare function incompleteInstallMessage(err: unknown, resolvePackageRoot?: PackageRootResolver): string | null;
+/** Bounded, scrubber-safe diagnostics for an unattributable esm-loader ENOENT. */
+export type IncompleteInstallDiagnostics = {
+    packageRoot: string;
+    packageJsonExists: boolean;
+    nodeModulesExists: boolean;
+    esmLoaderFrame: boolean;
+    code: string;
+};
+/**
+ * When an esm-loader ENOENT reaches the capture path WITHOUT being suppressed —
+ * the exact shape the delivered HQ-CLI-1M payload arrived in, where neither the
+ * exception value nor node_system_error carried a `path` — return a bounded
+ * `contexts.incomplete_install` block so the next occurrence carries the
+ * evidence this one lacked; otherwise return undefined (bare capture). Built
+ * with the byte-capped, scrubber-safe discipline of package-root-diagnostics.ts:
+ * the resolved package root and whether its package.json / node_modules exist,
+ * the loader-frame marker, and the bounded errno code — never a caller argv,
+ * query, or user-minted value. Never throws.
+ *
+ * main.ts attaches this on the generic capture path exactly as
+ * qmdSpawnFailureCaptureContext already does.
+ */
+export declare function incompleteInstallCaptureContext(err: unknown, resolvePackageRoot?: PackageRootResolver, fileSystem?: Pick<typeof fs, "existsSync">): {
+    incomplete_install: IncompleteInstallDiagnostics;
+} | undefined;
+//# sourceMappingURL=incomplete-install-error.d.ts.map

package/dist/utils/incomplete-install-error.js

@@ -0,0 +1,250 @@
+// src/utils/incomplete-install-error.ts
+//
+// Classify an IN-PROCESS module-load failure that means hq-cli's OWN globally
+// installed package tree is not intact at the moment it loads a module — the
+// caller's incomplete install, not an hq-cli code defect. Sibling in spirit to
+// qmd-module-missing-error.ts (HQ-CLI-Y), but keyed on the ERROR OBJECT of a
+// failure inside THIS process rather than a qmd child's captured stderr, which
+// is the gap HQ-CLI-Y's classifier cannot cover.
+//
+// Two shapes, one cause — a partial/interrupted global install left a file
+// unwritten, or a concurrent global install rewrote the running tree
+// underneath a command:
+//
+//   HQ-CLI-1N (Sentry 7714890525) — CJS, in-process. `hq core timeout-guard`
+//   loads the mesh presence client, whose `import mqtt` pulls a chain that ends
+//   at js-sdsl requiring a RELATIVE sibling (`./Base/TreeIterator`) that is
+//   absent on disk inside hq-cli's own bundled node_modules. Node throws
+//   `Error{ code: 'MODULE_NOT_FOUND', requireStack: [...] }`. A relative
+//   specifier internal to a third-party package can only be a truncated on-disk
+//   copy, never an hq-cli manifest defect.
+//
+//   HQ-CLI-1M (Sentry 7714870912) — ESM load, in-process. A module that existed
+//   at RESOLVE was gone at READ (a concurrent writer rewrote the install tree),
+//   so Node's ESM loader raised `ENOENT` from getSourceSync/readFileSync/openSync
+//   with an `esm/…` loader frame in the stack. A merely-absent ESM module raises
+//   ERR_MODULE_NOT_FOUND at resolve, never ENOENT at load; an ENOENT at load
+//   proves the file vanished between resolve and read.
+//
+// Both shapes carry no hq-cli frames, reach the boundary's final `else`, and —
+// before this classifier — filed a bare captureException plus an unactionable
+// `hq: <fallback>` line. The disposition is the one HQ-CLI-Y already
+// established: an incomplete install is the caller's machine, so the CLI prints
+// an input-free reinstall remedy and skips Sentry capture.
+//
+// The gate is deliberately narrow so neither an hq-cli packaging fault nor
+// user free-text can trip it. Only structured fields are read — `code`,
+// `syscall`, `path`, `requireStack`, and the stack's loader-frame marker, plus
+// the first message line for the CJS specifier. THREE independent narrowings
+// keep a genuine hq-cli defect reportable:
+//   1. The failing file must sit under `<packageRoot>/node_modules/` — a
+//      third-party file hq-cli does not author. A miss under `<packageRoot>/dist`
+//      or `/assets` is hq-cli's OWN shipped output and stays captured.
+//   2. The CJS shape additionally requires a RELATIVE specifier — a
+//      bare-specifier miss (`Cannot find module 'mqtt'`) can be an undeclared
+//      dependency (an hq-cli manifest defect) and stays captured.
+//   3. The ESM shape additionally requires an esm-loader frame — an ordinary
+//      `fs.readFileSync` ENOENT written by hq's own code stays captured.
+import * as fs from "fs";
+import * as path from "path";
+import { packageRoot } from "./hq-roots.js";
+import { boundedDiagnosticValue } from "./package-root-diagnostics.js";
+/**
+ * The actionable remedy shown to the operator. Input-free — nothing from the
+ * error, the argv, or the filesystem is interpolated — so there is no injection
+ * surface and no way to inflate Sentry grouping, matching the bounded-remedy
+ * discipline of every sibling classifier. Covers BOTH sub-cases in the order a
+ * user should try them: re-run first (an install that finished mid-run leaves
+ * the next invocation healthy), then reinstall if it persists.
+ */
+export const INCOMPLETE_INSTALL_REMEDY = "hq couldn't load part of its own installed files, so the hq install tree is " +
+    "incomplete on this machine — most often because a global install (its own " +
+    "self-update, the desktop background installer, another hq process, or a " +
+    "hand-run install) rewrote the package while this command was running, or an " +
+    "earlier install was interrupted before every file was written. Run the " +
+    "command again first: an install that finished mid-run leaves the next " +
+    "invocation healthy. If it keeps failing, reinstall hq — for a global install " +
+    "run `npm i -g @indigoai-us/hq-cli` (or the pnpm equivalent, " +
+    "`pnpm add -g @indigoai-us/hq-cli`).";
+/** A relative module specifier — `./x`, `../x`, `.\x`, `..\x`. */
+const RELATIVE_SPECIFIER = /^\.\.?[\\/]/;
+/** A Node ESM loader frame — proves the ENOENT came from the module loader, not hq's own fs call. */
+const ESM_LOADER_FRAME = /node:internal[\\/]modules[\\/]esm[\\/]/;
+const ROOT_DIAGNOSTIC_BYTES = 256;
+const CODE_DIAGNOSTIC_BYTES = 32;
+/**
+ * packageRoot() walks up from the compiled module and THROWS
+ * PackageRootResolutionError when it cannot resolve. This classifier runs inside
+ * beforeSend on EVERY event, so it must never throw — a resolution failure
+ * returns null and the error stays captured.
+ */
+function safePackageRoot() {
+    try {
+        return packageRoot();
+    }
+    catch {
+        return null;
+    }
+}
+/** Call a (possibly injected) resolver without letting it throw. */
+function resolveRootSafely(resolve) {
+    try {
+        return resolve();
+    }
+    catch {
+        return null;
+    }
+}
+/** Fold `\`/`/` runs to a single `/` and drop any trailing separator. */
+function foldSeparators(p) {
+    return p.replace(/[\\/]+/g, "/").replace(/\/+$/, "");
+}
+/** A Windows-shaped absolute path (drive letter or UNC), regardless of host OS. */
+function looksWin32(p) {
+    return /^[a-zA-Z]:[\\/]/.test(p) || /^\\\\/.test(p);
+}
+/**
+ * Normalise a path for prefix comparison: separators folded, and case folded
+ * ONLY for a Windows-shaped path (drive-letter case and AppData\Roaming casing
+ * drift there, but POSIX paths are case-sensitive and must stay so). Detecting
+ * win32 by the path's SHAPE — not `process.platform` — lets the reported
+ * Windows path classify on a Linux CI runner.
+ */
+function normalizeForCompare(p) {
+    const folded = foldSeparators(p);
+    return looksWin32(p) ? folded.toLowerCase() : folded;
+}
+/**
+ * True when `candidate` lives under `<root>/node_modules/`. Anchored at a true
+ * directory boundary (`<root>` + sep + `node_modules` + sep) so a sibling such
+ * as `<root>-old/node_modules/...` can never match.
+ */
+function isUnderNodeModules(candidate, root) {
+    if (!candidate || !root)
+        return false;
+    const prefix = `${normalizeForCompare(root)}/node_modules/`;
+    return normalizeForCompare(candidate).startsWith(prefix);
+}
+/** The failing specifier from a `Cannot find module '<spec>'` message, or null. */
+function parseMissingSpecifier(message) {
+    if (typeof message !== "string")
+        return null;
+    const match = message.match(/Cannot find module ['"]([^'"]+)['"]/);
+    return match ? match[1] : null;
+}
+/** True when `stack` carries a Node ESM loader frame. */
+function hasEsmLoaderFrame(stack) {
+    return typeof stack === "string" && ESM_LOADER_FRAME.test(stack);
+}
+/**
+ * The ESM-loader ENOENT SIGNATURE, independent of whether a usable `path`
+ * survived: `code === 'ENOENT'`, `syscall === 'open'`, and an esm-loader frame
+ * in the stack. This is the shape the instrumentation fallback attaches context
+ * to; the message classifier additionally requires a `path` under node_modules.
+ */
+function isEsmLoaderEnoent(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const record = err;
+    return (record.code === "ENOENT" &&
+        record.syscall === "open" &&
+        hasEsmLoaderFrame(record.stack));
+}
+/**
+ * If `err` is an in-process incomplete-install module-load failure — either the
+ * CJS relative-sibling shape (HQ-CLI-1N) or the ESM vanished-file shape
+ * (HQ-CLI-1M), with the failing file confirmed under `<packageRoot>/node_modules/`
+ * — return the actionable, input-free reinstall remedy; otherwise return null.
+ *
+ * Mirrors qmdModuleMissingMessage so the top-level handler and beforeSend branch
+ * the same way: a non-null result means print-the-remedy-and-skip-Sentry, null
+ * means "handle as usual (capture to Sentry)". Never throws — a resolver that
+ * fails yields null.
+ */
+export function incompleteInstallMessage(err, resolvePackageRoot = safePackageRoot) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    const code = typeof record.code === "string" ? record.code : undefined;
+    if (code !== "MODULE_NOT_FOUND" && code !== "ENOENT")
+        return null;
+    const root = resolveRootSafely(resolvePackageRoot);
+    if (!root)
+        return null;
+    if (code === "MODULE_NOT_FOUND") {
+        // Shape A (CJS, HQ-CLI-1N): a RELATIVE specifier internal to a package under
+        // the running install's node_modules can only be a truncated on-disk copy.
+        const requireStack = record.requireStack;
+        if (!Array.isArray(requireStack) || typeof requireStack[0] !== "string") {
+            return null;
+        }
+        const specifier = parseMissingSpecifier(record.message);
+        if (specifier === null || !RELATIVE_SPECIFIER.test(specifier))
+            return null;
+        return isUnderNodeModules(requireStack[0], root)
+            ? INCOMPLETE_INSTALL_REMEDY
+            : null;
+    }
+    // Shape B (ESM load, HQ-CLI-1M): an ENOENT from the module loader for a file
+    // that was present at resolve and gone at read.
+    if (record.syscall !== "open")
+        return null;
+    if (typeof record.path !== "string")
+        return null;
+    if (!hasEsmLoaderFrame(record.stack))
+        return null;
+    return isUnderNodeModules(record.path, root)
+        ? INCOMPLETE_INSTALL_REMEDY
+        : null;
+}
+/**
+ * When an esm-loader ENOENT reaches the capture path WITHOUT being suppressed —
+ * the exact shape the delivered HQ-CLI-1M payload arrived in, where neither the
+ * exception value nor node_system_error carried a `path` — return a bounded
+ * `contexts.incomplete_install` block so the next occurrence carries the
+ * evidence this one lacked; otherwise return undefined (bare capture). Built
+ * with the byte-capped, scrubber-safe discipline of package-root-diagnostics.ts:
+ * the resolved package root and whether its package.json / node_modules exist,
+ * the loader-frame marker, and the bounded errno code — never a caller argv,
+ * query, or user-minted value. Never throws.
+ *
+ * main.ts attaches this on the generic capture path exactly as
+ * qmdSpawnFailureCaptureContext already does.
+ */
+export function incompleteInstallCaptureContext(err, resolvePackageRoot = safePackageRoot, fileSystem = fs) {
+    if (!isEsmLoaderEnoent(err))
+        return undefined;
+    // Only instrument what we did NOT already confidently suppress: a path under
+    // node_modules is classified and printed above, never captured.
+    if (incompleteInstallMessage(err, resolvePackageRoot) !== null)
+        return undefined;
+    const record = err;
+    const root = resolveRootSafely(resolvePackageRoot);
+    const code = typeof record.code === "string" ? record.code : "";
+    let packageJsonExists = false;
+    let nodeModulesExists = false;
+    if (root) {
+        try {
+            packageJsonExists = fileSystem.existsSync(path.join(root, "package.json"));
+        }
+        catch {
+            packageJsonExists = false;
+        }
+        try {
+            nodeModulesExists = fileSystem.existsSync(path.join(root, "node_modules"));
+        }
+        catch {
+            nodeModulesExists = false;
+        }
+    }
+    return {
+        incomplete_install: {
+            packageRoot: boundedDiagnosticValue(root ?? "<unresolved>", ROOT_DIAGNOSTIC_BYTES),
+            packageJsonExists,
+            nodeModulesExists,
+            esmLoaderFrame: true,
+            code: boundedDiagnosticValue(code, CODE_DIAGNOSTIC_BYTES),
+        },
+    };
+}
+//# sourceMappingURL=incomplete-install-error.js.map

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