fix: add 403 scope guidance to issue list error handling (CLI-97) (#508)

## Problem

When `sentry issue list` gets 403 Forbidden, the error shows a bare
message without guidance. Affects **41 users**
([CLI-97](https://sentry.sentry.io/issues/7294207811/)).

## Fix

Added `build403Detail()` helper and `enrichIssueListError()` that enrich
403 errors with token scope suggestions — matching the guidance added to
org listing in PR #498:

```
Failed to fetch issues from 1 project(s): API request failed: 403 Forbidden
  Suggestions:
    • Your auth token may lack the required scopes (org:read, project:read)
    • Re-authenticate with: sentry auth login
    • Verify project membership: sentry project list <org>/
```

Applied to both code paths (`handleResolvedTargets` and org-all mode).
The `enrichIssueListError()` helper DRYs up the 400/403 enrichment used
by both paths.

Author: BYK

AGENTS.md

@@ -830,6 +830,9 @@ mock.module("./some-module", () => ({
 <!-- lore:019cb8c2-d7b5-780c-8a9f-d20001bc198f -->
 * **Install script: BSD sed and awk JSON parsing breaks OCI digest extraction**: The install script parses OCI manifests with awk (no jq). Key trap: BSD sed \`\n\` is literal, not newline. Fix: single awk pass tracking last-seen \`"digest"\`, printing when \`"org.opencontainers.image.title"\` matches target. The config digest (\`sha256:44136fa...\`) is a 2-byte \`{}\` blob — downloading it instead of the real binary causes \`gunzip: unexpected end of file\`.
 
+<!-- lore:019d0b04-ccec-7bd2-a5ca-732e7064cc1a -->
+* **Multi-region fan-out: distinguish all-403 from empty orgs with hasSuccessfulRegion flag**: The multi-region org listing fan-out (\`listOrganizationsUncached\` in \`src/lib/api/organizations.ts\`) uses \`Promise.allSettled\` to collect results from all regions. When checking whether to propagate a 403 error, don't use \`flatResults.length === 0\` alone — a region returning 200 OK with zero orgs pushes nothing into \`flatResults\`, making it look like all regions failed. Track a separate \`hasSuccessfulRegion\` boolean set on any \`"fulfilled"\` settlement. Only re-throw the 403 \`ApiError\` when \`!hasSuccessfulRegion && lastScopeError\` — this correctly distinguishes "all regions returned 403" from "some regions had no orgs."
+
 <!-- lore:019c969a-1c90-7041-88a8-4e4d9a51ebed -->
 * **Multiple mockFetch calls replace each other — use unified mocks for multi-endpoint tests**: Bun test mocking gotchas: (1) \`mockFetch()\` replaces \`globalThis.fetch\` — calling it twice replaces the first mock. Use a single unified fetch mock dispatching by URL pattern. (2) \`mock.module()\` pollutes the module registry for ALL subsequent test files. Tests using it must live in \`test/isolated/\` and run via \`test:isolated\`. This also causes \`delta-upgrade.test.ts\` to fail when run alongside \`test/isolated/delta-upgrade.test.ts\` — the isolated test's \`mock.module()\` replaces \`CLI\_VERSION\` for all subsequent files. (3) For \`Bun.spawn\`, use direct property assignment in \`beforeEach\`/\`afterEach\`.
 
@@ -838,6 +841,9 @@ mock.module("./some-module", () => ({
 
 ### Pattern
 
+<!-- lore:019d0b04-ccf7-7e74-a049-2ca6b8faa85f -->
+* **Cursor Bugbot review comments: fix valid bugs before merging**: Cursor Bugbot sometimes catches real logic bugs in PRs (not just style). In CLI-89, Bugbot identified that \`flatResults.length === 0\` was an incorrect proxy for "all regions failed" since fulfilled-but-empty regions are indistinguishable from rejected ones. Always read Bugbot's full comment body (via \`gh api repos/OWNER/REPO/pulls/NUM/comments\`) and fix valid findings before merging. Bugbot comments include a \`BUGBOT\_BUG\_ID\` HTML comment for tracking.
+
 <!-- lore:019c972c-9f11-7c0d-96ce-3f8cc2641175 -->
 * **Org-scoped SDK calls follow getOrgSdkConfig + unwrapResult pattern**: All org-scoped API calls in src/lib/api-client.ts: (1) call \`getOrgSdkConfig(orgSlug)\` for regional URL + SDK config, (2) spread into SDK function: \`{ ...config, path: { organization\_id\_or\_slug: orgSlug, ... } }\`, (3) pass to \`unwrapResult(result, errorContext)\`. Shared helpers \`resolveAllTargets\`/\`resolveOrgAndProject\` must NOT call \`fetchProjectId\` — commands that need it enrich targets themselves.
 

src/commands/issue/list.ts

@@ -841,17 +841,7 @@ async function handleOrgAllIssues(
         )
     );
   } catch (error) {
-    // Enrich 400 errors with the same suggestions as handleResolvedTargets
-    // (CLI-BY, 23 users). The org-all path was missing these hints.
-    if (error instanceof ApiError && error.status === 400) {
-      throw new ApiError(
-        error.message,
-        error.status,
-        build400Detail(error.detail, flags),
-        error.endpoint
-      );
-    }
-    throw error;
+    throw enrichIssueListError(error, flags);
   }
   const { issues, nextCursor } = issuesResult;
 
@@ -966,6 +956,63 @@ function build400Detail(
   return lines.join("\n  ");
 }
 
+/**
+ * Enrich an API error from issue listing with actionable suggestions.
+ *
+ * Handles both 400 (query/parameter) and 403 (permission) errors.
+ * Re-throws non-ApiError and unhandled statuses unchanged.
+ */
+function enrichIssueListError(
+  error: unknown,
+  flags: Pick<ListFlags, "query" | "period">
+): never {
+  if (error instanceof ApiError) {
+    if (error.status === 400) {
+      throw new ApiError(
+        error.message,
+        error.status,
+        build400Detail(error.detail, flags),
+        error.endpoint
+      );
+    }
+    if (error.status === 403) {
+      throw new ApiError(
+        error.message,
+        error.status,
+        build403Detail(error.detail),
+        error.endpoint
+      );
+    }
+  }
+  throw error;
+}
+
+/**
+ * Build an enriched error detail for 403 Forbidden responses.
+ *
+ * Suggests checking token scopes and project membership — the most common
+ * causes of 403 on the issues endpoint (CLI-97, 41 users).
+ *
+ * @param originalDetail - The API response detail (may be undefined)
+ * @returns Enhanced detail string with suggestions
+ */
+function build403Detail(originalDetail: string | undefined): string {
+  const lines: string[] = [];
+
+  if (originalDetail) {
+    lines.push(originalDetail, "");
+  }
+
+  lines.push(
+    "Suggestions:",
+    "  • Your auth token may lack the required scopes (org:read, project:read)",
+    "  • Re-authenticate with: sentry auth login",
+    "  • Verify project membership: sentry project list <org>/"
+  );
+
+  return lines.join("\n  ");
+}
+
 /**
  * Handle auto-detect, explicit, and project-search modes.
  *
@@ -1118,10 +1165,12 @@ async function handleResolvedTargets(
     // or parameters are likely malformed. Common causes: invalid Sentry
     // search syntax, unsupported period for the org's data retention.
     if (first instanceof ApiError) {
-      const detail =
-        first.status === 400
-          ? build400Detail(first.detail, flags)
-          : first.detail;
+      let detail = first.detail;
+      if (first.status === 400) {
+        detail = build400Detail(first.detail, flags);
+      } else if (first.status === 403) {
+        detail = build403Detail(first.detail);
+      }
       throw new ApiError(
         `${prefix}: ${first.message}`,
         first.status,
@@ -1130,7 +1179,7 @@ async function handleResolvedTargets(
       );
     }
 
-    throw new Error(`${prefix}.\n${first.message}`);
+    throw new Error(`${prefix}: ${first.message}`);
   }
 
   const isMultiProject = validResults.length > 1;