@indigoai-us/hq-cli 5.77.5 → 5.77.7

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [5.77.7]
+
+### Fixed
+
+- Updated `@indigoai-us/hq-cloud` to 6.14.19 so watched local deletes and
+  renames propagate during `hq sync`.
+
+## [5.77.6]
+
+### Fixed
+
+- Updated `@indigoai-us/hq-cloud` to 6.14.18, which includes the DEV-1974
+  symlink-loop convergence fix.
+
 ## [5.77.5]
 
 ### Added

package/dist/commands/integrations.js

@@ -53,6 +53,29 @@ export class IntegrationsCliError extends Error {
 function isClientError(status) {
     return status >= 400 && status < 500;
 }
+// The integration gateway answers `POST /v1/integrations/mcp` JSON-RPC-style: a
+// transport failure is a non-2xx HTTP status, but a GOVERNED refusal arrives as
+// HTTP 200 carrying a JSON-RPC `error` object (mirrors hq-pro's
+// integration-mcp/server.ts error mapping). These caller-side codes are the
+// JSON-RPC analog of a client 4xx — the caller's request/state/permission,
+// expected and actionable, not an hq-cli defect — so they are printed to the
+// user and skipped for Sentry capture (HQ-CLI-B):
+//   -32003 UNAUTHORIZED   — connection-level access denial, e.g. the
+//                           "You do not have access to this integration. Ask its
+//                           owner to share it with you." (IntegrationAccessDenied)
+//                           that flooded Sentry, plus ConnectionNotFound / a
+//                           read-only share rejecting a write.
+//   -32602 INVALID_PARAMS — an unknown tool or unsupported provider for the
+//                           connection (a bad request the caller can correct).
+// Everything else stays unexpected so a genuine fault still reaches Sentry:
+// PROVIDER_ERROR (-32050, an upstream provider fault), INTERNAL_ERROR (-32603),
+// CONFLICT (-32009, which the gateway also raises for a confirm queue being
+// unavailable or an owner notification failing — real backend faults worth a
+// report), METHOD_NOT_FOUND / PARSE_ERROR, and any absent or unrecognized code.
+const EXPECTED_GATEWAY_ERROR_CODES = new Set([-32003, -32602]);
+function isExpectedGatewayError(code) {
+    return code != null && EXPECTED_GATEWAY_ERROR_CODES.has(code);
+}
 // A 401 from ANY integration-gateway vault call means the caller's HQ session
 // is expired or missing — an expected auth state fixed by `hq login`, not an
 // hq-cli defect. Raise the same typed AuthError the vault company-resolution
@@ -142,7 +165,7 @@ export async function callGateway(token, params) {
         throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status) });
     }
     if (message.error) {
-        throw new IntegrationsCliError(message.error.message ?? "Integration gateway returned an error.");
+        throw new IntegrationsCliError(message.error.message ?? "Integration gateway returned an error.", { expected: isExpectedGatewayError(message.error.code) });
     }
     return message;
 }

package/dist/commands/reindex.d.ts

@@ -1,27 +1,9 @@
+import { Command } from 'commander';
 /**
- * hq reindex — surface namespaced skills, mirror the personal overlay into
- * core/, and regenerate the workers registry.
- *
- * Thin wrapper over @indigoai-us/hq-cloud's reindex(), which execs the bundled
- * scripts/reindex.sh against the HQ root. This command is what the hq-core
- * reindex hook shim calls on Stop / PostToolUse, and what sync()/rescue() call
- * after they change on-disk sources.
- *
- * Keeps a hidden `master-sync` alias for one release so an updated CLI still
- * answers a not-yet-updated hook shim (and vice-versa) during rollout.
- *
- * Lock-wait policy: reindex shares one per-root operation lock with `sync` and
- * `rescue`. By default acquisition waits UNBOUNDED for a live holder, which is
- * what a human running `hq reindex` interactively wants. But when invoked from a
- * Claude/Codex lifecycle hook (SessionStart / UserPromptSubmit / Stop /
- * PostToolUse), waiting is exactly wrong: if a sync/rescue is mid-flight, the
- * hook blocks the agent up to the host's per-hook timeout (the multi-minute
- * "Claude won't load in the HQ folder" spinner). `--from-hook` makes the hook
- * path refuse-fast (never wait); `--lock-timeout <sec>` bounds it explicitly.
- * The bound is applied via the HQ_OP_LOCK_TIMEOUT env var that the hq-cloud
- * operation lock honors, so it works even against an installed hq-cloud build
- * that predates a typed lock-timeout option.
+ * Check hook health without relying on lifecycle hooks. A fully disabled
+ * configuration is repaired only after a successful reindex; partial and
+ * malformed configurations remain untouched and receive recovery guidance.
  */
-import { Command } from 'commander';
+export declare function repairExtremeHookDrift(hqRoot: string, allowRepair?: boolean): void;
 export declare function registerReindexCommand(program: Command): void;
 //# sourceMappingURL=reindex.d.ts.map

package/dist/commands/reindex.js

@@ -1,4 +1,208 @@
-import { reindex } from '@indigoai-us/hq-cloud';
+/**
+ * hq reindex — surface namespaced skills, mirror the personal overlay into
+ * core/, and regenerate the workers registry.
+ *
+ * Thin wrapper over @indigoai-us/hq-cloud's reindex(), which execs the bundled
+ * scripts/reindex.sh against the HQ root. This command is what the hq-core
+ * reindex hook shim calls on Stop / PostToolUse, and what sync()/rescue() call
+ * after they change on-disk sources.
+ *
+ * Keeps a hidden `master-sync` alias for one release so an updated CLI still
+ * answers a not-yet-updated hook shim (and vice-versa) during rollout.
+ *
+ * Lock-wait policy: reindex shares one per-root operation lock with `sync` and
+ * `rescue`. By default acquisition waits UNBOUNDED for a live holder, which is
+ * what a human running `hq reindex` interactively wants. But when invoked from a
+ * Claude/Codex lifecycle hook (SessionStart / UserPromptSubmit / Stop /
+ * PostToolUse), waiting is exactly wrong: if a sync/rescue is mid-flight, the
+ * hook blocks the agent up to the host's per-hook timeout (the multi-minute
+ * "Claude won't load in the HQ folder" spinner). `--from-hook` makes the hook
+ * path refuse-fast (never wait); `--lock-timeout <sec>` bounds it explicitly.
+ * The bound is applied via the HQ_OP_LOCK_TIMEOUT env var that the hq-cloud
+ * operation lock honors, so it works even against an installed hq-cloud build
+ * that predates a typed lock-timeout option.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+import { reindex, rescue } from '@indigoai-us/hq-cloud';
+import { findHqRoot } from '../utils/manifest.js';
+const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse'];
+const HOOK_CHECK_RELATIVE_PATH = path.join('core', 'scripts', 'check-hq-hooks.sh');
+/** Resolve the same root the repair/check commands must operate on. */
+function resolveHqRoot(repoRoot) {
+    const root = repoRoot ?? findHqRoot();
+    try {
+        return fs.realpathSync(root);
+    }
+    catch {
+        return path.resolve(root);
+    }
+}
+function isHqRoot(hqRoot) {
+    return (fs.existsSync(path.join(hqRoot, 'companies')) &&
+        (fs.existsSync(path.join(hqRoot, '.claude')) ||
+            fs.existsSync(path.join(hqRoot, 'core')) ||
+            fs.existsSync(path.join(hqRoot, 'personal'))));
+}
+function hasCommandHook(value) {
+    if (!Array.isArray(value))
+        return false;
+    return value.some((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return false;
+        const hooks = entry.hooks;
+        if (!Array.isArray(hooks))
+            return false;
+        return hooks.some((hook) => !!hook &&
+            typeof hook === 'object' &&
+            hook.type === 'command' &&
+            typeof hook.command === 'string' &&
+            hook.command.trim().length > 0);
+    });
+}
+/**
+ * Run the release health checker when it is available. Its diagnostics cover
+ * runtime/configuration issues outside the safe repair scope; the JSON check
+ * below additionally recognizes UserPromptSubmit, which older checkers omit.
+ */
+function runShippedHookCheck(hqRoot) {
+    const checker = path.join(hqRoot, HOOK_CHECK_RELATIVE_PATH);
+    if (!fs.existsSync(checker))
+        return undefined;
+    try {
+        const result = spawnSync('bash', [checker, '--root', hqRoot], {
+            encoding: 'utf8',
+            stdio: 'pipe',
+        });
+        if (result.error)
+            return undefined;
+        return {
+            status: result.status ?? 1,
+            output: `${result.stderr ?? ''}${result.stdout ?? ''}`.trim(),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function inspectHookHealth(hqRoot) {
+    const checkerResult = runShippedHookCheck(hqRoot);
+    const settingsPath = path.join(hqRoot, '.claude', 'settings.json');
+    if (!fs.existsSync(settingsPath)) {
+        return { state: 'extreme', reason: '.claude/settings.json is missing' };
+    }
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    }
+    catch {
+        return { state: 'minor', reason: '.claude/settings.json is not valid JSON' };
+    }
+    if (!settings || typeof settings !== 'object') {
+        return { state: 'minor', reason: '.claude/settings.json is not an object' };
+    }
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== 'object') {
+        return { state: 'extreme', reason: 'no command hooks are declared' };
+    }
+    const commandEvents = HOOK_EVENTS.filter((event) => hasCommandHook(hooks[event]));
+    if (commandEvents.length === 0) {
+        return { state: 'extreme', reason: 'no SessionStart, UserPromptSubmit, or PreToolUse command hook is declared' };
+    }
+    if (commandEvents.length !== HOOK_EVENTS.length) {
+        return {
+            state: 'minor',
+            reason: `missing command hook wiring for ${HOOK_EVENTS.filter((event) => !commandEvents.includes(event)).join(', ')}`,
+        };
+    }
+    if (checkerResult !== undefined && checkerResult.status !== 0) {
+        return {
+            state: 'minor',
+            reason: checkerResult.output || 'the shipped core/scripts/check-hq-hooks.sh check failed',
+        };
+    }
+    return { state: 'healthy' };
+}
+function printHookHealthWarning(hqRoot, reason) {
+    console.warn(`
+HQ hook health warning: lifecycle hooks may not fire in ${hqRoot}.
+  - ${reason}
+
+Repair the project settings with:
+  hq rescue -y --paths .claude
+
+If the repair is unavailable, update HQ and re-run \`hq reindex\`.
+For Claude Desktop, open the HQ root itself as the project (not a parent or child folder).
+For an SDK launch, set both \`cwd\` to the HQ root and \`settingSources: ["project"]\`.
+See core/docs/hq/HOOKS-NOT-FIRING.md for the recovery procedure.`);
+}
+function installedCoreRef(hqRoot) {
+    for (const relativePath of [path.join('core', 'core.yaml'), 'core.yaml']) {
+        try {
+            const core = yaml.load(fs.readFileSync(path.join(hqRoot, relativePath), 'utf8'));
+            if (typeof core?.hqVersion === 'string' && core.hqVersion.trim()) {
+                return core.hqVersion.startsWith('v') ? core.hqVersion : `v${core.hqVersion}`;
+            }
+        }
+        catch {
+            // The installed version is optional; rescue will use the production default.
+        }
+    }
+    return undefined;
+}
+/** Rescue writes detailed progress directly to stdio. Reindex only needs a one-line notice. */
+function runSilently(operation) {
+    const writeStdout = process.stdout.write;
+    const writeStderr = process.stderr.write;
+    const discard = (() => true);
+    process.stdout.write = discard;
+    process.stderr.write = discard;
+    try {
+        return operation();
+    }
+    finally {
+        process.stdout.write = writeStdout;
+        process.stderr.write = writeStderr;
+    }
+}
+/**
+ * Check hook health without relying on lifecycle hooks. A fully disabled
+ * configuration is repaired only after a successful reindex; partial and
+ * malformed configurations remain untouched and receive recovery guidance.
+ */
+export function repairExtremeHookDrift(hqRoot, allowRepair = true) {
+    // `hq reindex` can still be invoked from an arbitrary directory. Never turn
+    // an absent settings file there into a rescue attempt.
+    if (!isHqRoot(hqRoot))
+        return;
+    const health = inspectHookHealth(hqRoot);
+    if (health.state === 'healthy')
+        return;
+    printHookHealthWarning(hqRoot, health.reason);
+    if (health.state === 'minor' || !allowRepair)
+        return;
+    try {
+        const result = runSilently(() => rescue({
+            hqRoot,
+            source: 'indigoai-us/hq-core',
+            ref: installedCoreRef(hqRoot),
+            paths: ['.claude'],
+            assumeYes: true,
+        }));
+        const afterRepair = inspectHookHealth(hqRoot);
+        if (result.status === 0 && afterRepair.state === 'healthy') {
+            console.log('reindex: repaired HQ hook config');
+            return;
+        }
+        printHookHealthWarning(hqRoot, afterRepair.state === 'healthy' ? `rescue exited ${result.status}` : afterRepair.reason);
+    }
+    catch {
+        // A transient clone/transport failure must not turn reindex into a fatal command.
+        printHookHealthWarning(hqRoot, 'hook configuration repair could not run');
+    }
+}
 export function registerReindexCommand(program) {
     program
         .command('reindex')
@@ -29,6 +233,7 @@ export function registerReindexCommand(program) {
             process.env.HQ_OP_LOCK_TIMEOUT = String(lockTimeoutSec);
         }
         const { status } = reindex({ repoRoot: opts.repoRoot });
+        repairExtremeHookDrift(resolveHqRoot(opts.repoRoot), status === 0);
         process.exit(status);
     });
 }

package/dist/utils/version-gate.d.ts

@@ -41,6 +41,40 @@ interface VersionCheckResponse {
 export declare function npmPrefixFromPackageDir(pkgDir: string): string | null;
 export declare function resolveRunningPrefix(): string | null;
 export declare function buildPrefixedInstallArgv(prefix: string): string[];
+/**
+ * Filesystem surface used by {@link cleanStalePartialInstall}. Injected so the
+ * cleanup logic is unit-testable without touching a real global prefix.
+ */
+export interface StaleInstallFs {
+    readdirSync: (dir: string) => string[];
+    existsSync: (target: string) => boolean;
+    readFileSync: (target: string, encoding: "utf-8") => string;
+    rmSync: (target: string, options: {
+        recursive: boolean;
+        force: boolean;
+    }) => void;
+}
+/**
+ * Remove leftover artifacts from an interrupted `npm install -g` so a retry can
+ * succeed. npm unpacks a package into a `.<pkg>-<rand>` staging dir alongside
+ * the final location and then renames it into place; if a previous run was
+ * killed mid-rename (or a half-written package dir survives), every subsequent
+ * install fails with `ENOTEMPTY` because npm cannot atomically rename over the
+ * non-empty leftover. npm does not self-heal this — the stale dir must be
+ * removed first.
+ *
+ * To stay safe we only ever delete:
+ *   - dot-prefixed npm staging dirs for THIS package (`.hq-cli-*`), and
+ *   - a package dir whose `package.json` is missing/unreadable or whose `name`
+ *     is not exactly {@link CLI_NAME} (i.e. a genuinely partial/foreign dir).
+ *
+ * A healthy install (valid `package.json`, `name === CLI_NAME`) is never
+ * touched, so an ordinary version bump still flows through npm untouched.
+ *
+ * Returns the list of removed paths — empty when there was nothing to clean, so
+ * callers can gate a reinstall retry on `removed.length > 0`.
+ */
+export declare function cleanStalePartialInstall(prefix: string, fs?: StaleInstallFs): string[];
 /**
  * Run the upgrade command in a blocking subprocess. Inherits stdio so the
  * user sees the npm progress. We do NOT auto-rerun the CLI on completion —
@@ -69,6 +103,7 @@ declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: {
     performUpdateString?: (command: string) => UpdateResult;
     resolvePrefix?: () => string | null;
     runner?: UpdateRunner;
+    cleanStale?: (prefix: string) => string[];
 }): never;
 /**
  * Public entry point. Call before commander parses argv. Blocks the CLI on
@@ -92,6 +127,7 @@ export declare const __test__: {
     ENDPOINT_PATH: string;
     FETCH_TIMEOUT_MS: number;
     buildPrefixedInstallArgv: typeof buildPrefixedInstallArgv;
+    cleanStalePartialInstall: typeof cleanStalePartialInstall;
     enforceUpdateRequired: typeof enforceUpdateRequired;
     npmPrefixFromPackageDir: typeof npmPrefixFromPackageDir;
     performUpdate: typeof performUpdate;

package/dist/utils/version-gate.js

@@ -28,7 +28,7 @@
  * to silence both check + gate).
  */
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
@@ -86,6 +86,90 @@ export function resolveRunningPrefix() {
 export function buildPrefixedInstallArgv(prefix) {
     return ["install", "-g", "--prefix", prefix, LATEST_PACKAGE_SPEC];
 }
+const nodeStaleInstallFs = {
+    readdirSync: (dir) => readdirSync(dir),
+    existsSync,
+    readFileSync: (target, encoding) => readFileSync(target, encoding),
+    rmSync,
+};
+function isHealthyPackageDir(pkgDir, fs) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf-8"));
+        return pkg.name === CLI_NAME;
+    }
+    catch {
+        return false; // missing / unreadable / malformed package.json ⇒ partial
+    }
+}
+/**
+ * Remove leftover artifacts from an interrupted `npm install -g` so a retry can
+ * succeed. npm unpacks a package into a `.<pkg>-<rand>` staging dir alongside
+ * the final location and then renames it into place; if a previous run was
+ * killed mid-rename (or a half-written package dir survives), every subsequent
+ * install fails with `ENOTEMPTY` because npm cannot atomically rename over the
+ * non-empty leftover. npm does not self-heal this — the stale dir must be
+ * removed first.
+ *
+ * To stay safe we only ever delete:
+ *   - dot-prefixed npm staging dirs for THIS package (`.hq-cli-*`), and
+ *   - a package dir whose `package.json` is missing/unreadable or whose `name`
+ *     is not exactly {@link CLI_NAME} (i.e. a genuinely partial/foreign dir).
+ *
+ * A healthy install (valid `package.json`, `name === CLI_NAME`) is never
+ * touched, so an ordinary version bump still flows through npm untouched.
+ *
+ * Returns the list of removed paths — empty when there was nothing to clean, so
+ * callers can gate a reinstall retry on `removed.length > 0`.
+ */
+export function cleanStalePartialInstall(prefix, fs = nodeStaleInstallFs) {
+    const removed = [];
+    const slash = CLI_NAME.indexOf("/");
+    const scope = slash === -1 ? null : CLI_NAME.slice(0, slash);
+    const leaf = slash === -1 ? CLI_NAME : CLI_NAME.slice(slash + 1);
+    const stagingPrefix = `.${leaf}-`;
+    // Global npm keeps packages under `<prefix>/lib/node_modules` (unix) while a
+    // bare `--prefix` dir (windows / some sandboxes) uses `<prefix>/node_modules`.
+    const nmRoots = [
+        path.join(prefix, "lib", "node_modules"),
+        path.join(prefix, "node_modules"),
+    ];
+    for (const nmRoot of nmRoots) {
+        // For a scoped package the staging dir + final dir both live inside the
+        // scope dir (`.../@indigoai-us/.hq-cli-<rand>`, `.../@indigoai-us/hq-cli`).
+        const parentDir = scope ? path.join(nmRoot, scope) : nmRoot;
+        let entries;
+        try {
+            entries = fs.readdirSync(parentDir);
+        }
+        catch {
+            continue; // this node_modules / scope dir doesn't exist here
+        }
+        for (const entry of entries) {
+            if (!entry.startsWith(stagingPrefix))
+                continue;
+            const target = path.join(parentDir, entry);
+            try {
+                fs.rmSync(target, { recursive: true, force: true });
+                removed.push(target);
+            }
+            catch {
+                // best-effort: a dir we can't remove (perms) just means the retry
+                // still fails and we fall through to the sudo / manual path.
+            }
+        }
+        const pkgDir = path.join(parentDir, leaf);
+        if (fs.existsSync(pkgDir) && !isHealthyPackageDir(pkgDir, fs)) {
+            try {
+                fs.rmSync(pkgDir, { recursive: true, force: true });
+                removed.push(pkgDir);
+            }
+            catch {
+                // best-effort (see above)
+            }
+        }
+    }
+    return removed;
+}
 /**
  * Hit POST /v1/client-version/check. Returns the parsed body on 200, or
  * `null` on any failure (caller treats as "no gate"). Tight 3s timeout —
@@ -208,6 +292,22 @@ function enforceUpdateRequired(decision, deps = {}) {
                 ? deps.performUpdateString(command)
                 : performUpdate(command, runner);
         })();
+    // A partial/corrupt global install leaves npm unable to atomically rename its
+    // freshly-unpacked package over a leftover directory, so the install above
+    // fails with ENOTEMPTY (e.g. a prior interrupted `npm install -g` left a
+    // half-written `hq-cli` package dir or a `.hq-cli-<rand>` staging dir under
+    // the prefix's node_modules). npm cannot self-heal this. Remove the stale
+    // artifacts and retry the install ONCE. Guarded on `cleaned.length > 0` so a
+    // plain EACCES on an otherwise-healthy prefix falls straight through to the
+    // sudo retry below without a redundant reinstall attempt.
+    if (!result.ok && prefix) {
+        const cleaner = deps.cleanStale ?? cleanStalePartialInstall;
+        const cleaned = cleaner(prefix);
+        if (cleaned.length > 0) {
+            console.error(chalk.dim(`  Removing stale partial install artifacts and retrying: ${cleaned.join(", ")}`));
+            result = performUpdateCommand("npm", primaryArgs, runner);
+        }
+    }
     // A root-owned global install (e.g. a system `/usr` install where the CLI runs
     // unprivileged — the outpost agent boxes) can't rewrite the prefix's bin dir,
     // so the install above fails with EACCES (`rename /usr/bin/hq`). Retry ONCE
@@ -269,6 +369,7 @@ export const __test__ = {
     ENDPOINT_PATH,
     FETCH_TIMEOUT_MS,
     buildPrefixedInstallArgv,
+    cleanStalePartialInstall,
     enforceUpdateRequired,
     npmPrefixFromPackageDir,
     performUpdate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.77.5",
+  "version": "5.77.7",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -22,7 +22,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "^6.14.14",
+    "@indigoai-us/hq-cloud": "^6.14.19",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "better-sqlite3": "^12.11.1",

package/pnpm-workspace.yaml

@@ -1,4 +1,4 @@
 allowBuilds:
   better-sqlite3: true
 minimumReleaseAgeExclude:
-  - '@indigoai-us/hq-cloud@6.14.14'
+  - '@indigoai-us/hq-cloud@6.14.14 || 6.14.18 || 6.14.19'

package/src/commands/integrations.test.ts

@@ -513,3 +513,121 @@ describe("integration gateway 401 → AuthError (HQ-CLI-9)", () => {
     expect((err as Error).message).toMatch(/monday rejected the board id/);
   });
 });
+
+// HQ-CLI-B: `hq integrations tools|call … --provider …` against a connection the
+// caller has NOT been granted returned HTTP 200 with a JSON-RPC error
+// { code: -32003, message: "You do not have access to this integration. Ask its
+// owner to share it with you.", data: { code: "IntegrationAccessDenied" } }.
+// `callGateway` threw an IntegrationsCliError WITHOUT `expected`, so it defaulted
+// to `expected === false` and the top-level handler shipped a GOVERNED, correct
+// access denial to Sentry as an error-level fatal — 40 identical, unfixable
+// events for one user. A caller-side JSON-RPC code (UNAUTHORIZED / INVALID_PARAMS)
+// is the analog of a client 4xx and must be printed to the user, not captured;
+// genuine server/provider/protocol faults must still report.
+describe("gateway JSON-RPC error classification (HQ-CLI-B)", () => {
+  function gatewayJsonRpcError(code: number | undefined, message: string, data?: unknown) {
+    return jsonResponse({
+      jsonrpc: "2.0",
+      id: "x",
+      error: { ...(code == null ? {} : { code }), message, ...(data ? { data } : {}) },
+    });
+  }
+
+  async function runGatewayCall(): Promise<unknown> {
+    return runCli([
+      "integrations",
+      "call",
+      "get_board_info",
+      "--provider",
+      "linear",
+      "--args",
+      "{}",
+    ]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+  }
+
+  it("marks the access-denied gateway error (-32003) as expected and preserves its actionable message", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        gatewayJsonRpcError(
+          -32003,
+          "You do not have access to this integration. Ask its owner to share it with you.",
+          { code: "IntegrationAccessDenied" },
+        ),
+      );
+
+    const err = await runGatewayCall();
+
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    // The regression: this was `false` and flooded Sentry with a governed denial.
+    expect((err as IntegrationsCliError).expected).toBe(true);
+    // A connection-level denial is NOT an expired session — never an AuthError.
+    expect(isAuthError(err)).toBe(false);
+    expect((err as Error).message).toContain("do not have access to this integration");
+  });
+
+  it("also marks access-denied as expected on the `tools` path (same callGateway seam)", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        gatewayJsonRpcError(
+          -32003,
+          "You do not have access to this integration. Ask its owner to share it with you.",
+        ),
+      );
+
+    const err = await runCli(["integrations", "tools", "--provider", "linear"]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    expect((err as IntegrationsCliError).expected).toBe(true);
+  });
+
+  it("marks an invalid-params gateway error (-32602) as expected", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(gatewayJsonRpcError(-32602, "Unknown integration tool: get_board_info"));
+
+    const err = await runGatewayCall();
+
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    expect((err as IntegrationsCliError).expected).toBe(true);
+  });
+
+  it("still reports genuine provider/internal/conflict gateway faults (expected === false)", async () => {
+    // -32050 PROVIDER_ERROR, -32603 INTERNAL_ERROR, and -32009 CONFLICT (which the
+    // gateway raises for a confirm queue being unavailable or an owner
+    // notification failing) are real faults that must keep reaching Sentry.
+    for (const code of [-32050, -32603, -32009]) {
+      vaultApiFetchMock
+        .mockResolvedValueOnce(connectionsResponse())
+        .mockResolvedValueOnce(gatewayJsonRpcError(code, "gateway fault"));
+
+      const err = await runGatewayCall();
+
+      expect(err).toBeInstanceOf(IntegrationsCliError);
+      expect((err as IntegrationsCliError).expected).toBe(false);
+      vaultApiFetchMock.mockClear();
+    }
+  });
+
+  it("reports a gateway error with no JSON-RPC code (unclassified → expected === false)", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(gatewayJsonRpcError(undefined, "codeless failure"));
+
+    const err = await runGatewayCall();
+
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    expect((err as IntegrationsCliError).expected).toBe(false);
+  });
+});