fix: only mention token scopes in 403 errors for env-var tokens

The regular 'sentry auth login' OAuth flow always grants all required
scopes, so suggesting to check token scopes is misleading for those
users. Now only shows scope guidance when using a custom env-var token
(SENTRY_AUTH_TOKEN / SENTRY_TOKEN). OAuth users see 'Re-authenticate
with: sentry auth login' instead.

Applied to both issue list (build403Detail) and org listing
(listOrganizationsInRegion) 403 handlers.

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");
     }
   });