fix: only mention token scopes in 403 errors for env-var tokens (#512)

## Follow-up to PR #508

Addresses review feedback: the regular `sentry auth login` OAuth flow
always grants all required scopes, so suggesting to check token scopes
is misleading for those users.

## Fix

Now checks `isEnvTokenActive()` to distinguish auth methods:

**OAuth users** (regular login):
```
You may not have access to this organization.
Re-authenticate with: sentry auth login
Verify project membership: sentry project list <org>/
```

**Env-var token users** (custom token):
```
Your SENTRY_AUTH_TOKEN token may lack the required scopes (org:read, project:read)
Check token scopes at: https://sentry.io/settings/auth-tokens/
Verify project membership: sentry project list <org>/
```

Applied to both locations:
- `build403Detail()` in issue list (`handleResolvedTargets` + org-all)
- `listOrganizationsInRegion()` in org listing

Author: BYK

AGENTS.md

@@ -836,6 +836,9 @@ mock.module("./some-module", () => ({
 <!-- 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\`.
 
+<!-- lore:019d0b36-5dae-722b-8094-aca5cfbb5527 -->
+* **Seer trial prompt requires interactive terminal — AI agents never see it**: The Seer trial prompt middleware in \`bin.ts\` (\`executeWithSeerTrialPrompt\`) checks \`isatty(0)\` before prompting. Most Seer callers are AI coding agents running non-interactively, so the prompt never fires and \`SeerError\` propagates with a generic message. Fix: \`SeerError.format()\` should include an actionable command like \`sentry trial start seer \<org>\` that non-interactive callers can execute directly. Also, \`handleSeerApiError\` was wrapping \`ApiError\` in plain \`Error\`, losing the type — the middleware's \`instanceof ApiError\` check then failed silently. Always return the original \`ApiError\` from error handlers to preserve type identity for downstream middleware.
+
 <!-- lore:019c9741-d78e-73b1-87c2-e360ef6c7475 -->
 * **useTestConfigDir without isolateProjectRoot causes DSN scanning of repo tree**: \`useTestConfigDir()\` creates temp dirs under \`.test-tmp/\` in the repo tree. Without \`{ isolateProjectRoot: true }\`, \`findProjectRoot\` walks up and finds the repo's \`.git\`, causing DSN detection to scan real source code and trigger network calls against test mocks (timeouts). Always pass \`isolateProjectRoot: true\` when tests exercise \`resolveOrg\`, \`detectDsn\`, or \`findProjectRoot\`.
 
@@ -844,6 +847,9 @@ mock.module("./some-module", () => ({
 <!-- 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:019d0b36-5da2-750c-b26f-630a2927bd79 -->
+* **findProjectsByPattern as fuzzy fallback for exact slug misses**: When \`findProjectsBySlug\` returns empty (no exact match), use \`findProjectsByPattern\` as a fallback to suggest similar projects. \`findProjectsByPattern\` does bidirectional word-boundary matching (\`matchesWordBoundary\`) against all projects in all orgs — the same logic used for directory name inference. In the \`project-search\` handler, call it after the exact miss, format matches as \`\<org>/\<slug>\` suggestions in the \`ResolutionError\`. This avoids a dead-end error for typos like 'patagonai' when 'patagon-ai' exists. Note: \`findProjectsByPattern\` makes additional API calls (lists all projects per org), so only call it on the failure path.
+
 <!-- 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

@@ -21,6 +21,7 @@ import {
   looksLikeIssueShortId,
   parseOrgProjectArg,
 } from "../../lib/arg-parsing.js";
+import { getActiveEnvVarName, isEnvTokenActive } from "../../lib/db/auth.js";
 import {
   buildPaginationContextKey,
   clearPaginationCursor,
@@ -1006,8 +1007,9 @@ function enrichIssueListError(
 /**
  * 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).
+ * Only mentions token scopes when using a custom env-var token
+ * (SENTRY_AUTH_TOKEN / SENTRY_TOKEN) since the regular `sentry auth login`
+ * OAuth flow always grants the required scopes.
  *
  * @param originalDetail - The API response detail (may be undefined)
  * @returns Enhanced detail string with suggestions
@@ -1019,12 +1021,18 @@ function build403Detail(originalDetail: string | undefined): string {
     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>/"
-  );
+  lines.push("Suggestions:");
+
+  if (isEnvTokenActive()) {
+    lines.push(
+      `  • Your ${getActiveEnvVarName()} token may lack the required scopes (org:read, project:read)`,
+      "  • Check token scopes at: https://sentry.io/settings/auth-tokens/"
+    );
+  } else {
+    lines.push("  • Re-authenticate with: sentry auth login");
+  }
+
+  lines.push("  • Verify project membership: sentry project list <org>/");
 
   return lines.join("\n  ");
 }

src/lib/api/organizations.ts

@@ -16,6 +16,7 @@ import {
   UserRegionsResponseSchema,
 } from "../../types/index.js";
 
+import { getActiveEnvVarName, isEnvTokenActive } from "../db/auth.js";
 import { ApiError, withAuthGuard } from "../errors.js";
 import {
   getApiBaseUrl,
@@ -64,20 +65,25 @@ export async function listOrganizationsInRegion(
     const data = unwrapResult(result, "Failed to list organizations");
     return data as unknown as SentryOrganization[];
   } catch (error) {
-    // Enrich 403 errors with token scope guidance (CLI-89, 24 users).
-    // A 403 from the organizations endpoint usually means the auth token
-    // lacks the org:read scope — either it's an internal integration token
-    // with limited scopes, or a self-hosted token without the right permissions.
+    // Enrich 403 errors with contextual guidance (CLI-89, 24 users).
+    // Only mention token scopes when using a custom env-var token —
+    // the regular `sentry auth login` OAuth flow always grants org:read.
     if (error instanceof ApiError && error.status === 403) {
       const lines: string[] = [];
       if (error.detail) {
         lines.push(error.detail, "");
       }
-      lines.push(
-        "Your auth token may lack the required 'org:read' scope.",
-        "Re-authenticate with: sentry auth login",
-        "Or check token scopes at: https://sentry.io/settings/auth-tokens/"
-      );
+      if (isEnvTokenActive()) {
+        lines.push(
+          `Your ${getActiveEnvVarName()} token may lack the required 'org:read' scope.`,
+          "Check token scopes at: https://sentry.io/settings/auth-tokens/"
+        );
+      } else {
+        lines.push(
+          "You may not have access to this organization.",
+          "Re-authenticate with: sentry auth login"
+        );
+      }
       throw new ApiError(
         error.message,
         error.status,

test/lib/api-client.multiregion.test.ts

@@ -192,7 +192,7 @@ describe("listOrganizationsInRegion", () => {
     expect(orgs[0].slug).toBe("us-org-1");
   });
 
-  test("enriches 403 error with token scope guidance", async () => {
+  test("enriches 403 error with re-auth guidance for OAuth users", async () => {
     globalThis.fetch = async () =>
       new Response(JSON.stringify({ detail: "You do not have permission" }), {
         status: 403,
@@ -209,9 +209,9 @@ describe("listOrganizationsInRegion", () => {
       expect(apiErr.status).toBe(403);
       // Should include the original detail
       expect(apiErr.detail).toContain("You do not have permission");
-      // Should include scope guidance
-      expect(apiErr.detail).toContain("org:read");
+      // OAuth users: suggest re-auth (not token scopes)
       expect(apiErr.detail).toContain("sentry auth login");
+      expect(apiErr.detail).not.toContain("org:read");
     }
   });
 
@@ -556,7 +556,8 @@ describe("listOrganizations (fan-out)", () => {
       expect(error).toBeInstanceOf(ApiError);
       const apiErr = error as ApiError;
       expect(apiErr.status).toBe(403);
-      expect(apiErr.detail).toContain("org:read");
+      // OAuth users: re-auth guidance (no scope hint)
+      expect(apiErr.detail).toContain("sentry auth login");
     }
   });