fix(issue): improve numeric issue ID resolution with org context and region routing

For bare numeric IDs (e.g. `sentry issue explain 99124558`), the resolved
issue had no org, causing `explain`/`plan` to fail with 'Organization is
required' even though the fetch succeeded. Fix: extract org from the
response permalink, and prefer org-scoped region-routed fetches when org
context is available from DSN/env/config.

Author: BYK

.gitignore

@@ -48,3 +48,6 @@ docs/.astro
 
 # Finder (MacOS) folder config
 .DS_Store
+
+# OpenCode
+.opencode/

AGENTS.md

@@ -622,3 +622,16 @@ mock.module("./some-module", () => ({
 | Add E2E tests | `test/e2e/` |
 | Test helpers | `test/model-based/helpers.ts` |
 | Add documentation | `docs/src/content/docs/` |
+
+<!-- This section is auto-maintained by lore (https://github.com/BYK/opencode-lore) -->
+## Long-term Knowledge
+
+### Gotcha
+
+<!-- lore:019c9741-d78e-73b1-87c2-e360ef6c7475 -->
+* **useTestConfigDir without isolateProjectRoot causes DSN scanning of repo tree**: In getsentry/cli tests, \`useTestConfigDir()\` creates temp dirs under \`.test-tmp/\` inside the repo tree. When code calls \`detectDsn(cwd)\` with this temp dir as cwd (e.g., via \`resolveOrg({ cwd })\`), \`findProjectRoot\` walks up from \`.test-tmp/prefix-xxx\` and finds the repo's \`.git\` directory, causing DSN detection to scan the actual source code for Sentry DSNs. This can trigger network calls that hit test fetch mocks (returning 404s or unexpected responses), leading to 5-second test timeouts. Fix: always use \`useTestConfigDir(prefix, { isolateProjectRoot: true })\` when the test exercises any code path that might call \`resolveOrg\`, \`detectDsn\`, or \`findProjectRoot\` with the config dir as cwd. The \`isolateProjectRoot\` option creates a \`.git\` directory inside the temp dir, stopping the upward walk immediately.
+<!-- lore:019c972c-9f0d-7c8e-95b1-7beda99c36a8 -->
+* **parseSentryUrl does not handle subdomain-style SaaS URLs**: The URL parser in src/lib/sentry-url-parser.ts now handles both path-based (\`/organizations/{org}/...\`) and subdomain-style (\`https://my-org.sentry.io/issues/123/\`) SaaS URLs. The \`matchSubdomainOrg()\` function extracts the org from the hostname when it ends with \`.sentry.io\`, supports \`/issues/{id}/\`, \`/issues/{id}/events/{eventId}/\`, and \`/traces/{traceId}/\` paths. Region subdomains (\`us\`, \`de\`) are filtered out by requiring org slugs to be longer than 2 characters. The \`baseUrl\` for subdomain URLs is the full \`scheme://host\` (e.g., \`https://my-org.sentry.io\`). \`DEFAULT\_SENTRY\_HOST\` is \`sentry.io\` (from constants.ts). The \`isSentrySaasUrl\` helper in sentry-urls.ts is imported to gate subdomain extraction to SaaS URLs only.
+<!-- lore:019c972c-9f0f-75cd-9e24-9bdbb1ac03d6 -->
+* **Numeric issue ID resolution returns org:undefined despite API success**: Numeric issue ID resolution now uses a multi-step approach in \`resolveNumericIssue()\` (extracted from \`resolveIssue\` to reduce cognitive complexity). Resolution order: (1) \`resolveOrg({ cwd })\` tries DSN/env/config for org context, (2) if org found, uses \`getIssueInOrg(org, id)\` with region routing, (3) if no org, falls back to unscoped \`getIssue(id)\`, (4) extracts org from \`issue.permalink\` via \`parseSentryUrl\` as final fallback. The \`explicit-org-numeric\` case now uses \`getIssueInOrg(parsed.org, id)\` instead of the unscoped endpoint. \`getIssueInOrg\` was added to api-client.ts using the SDK's \`retrieveAnIssue\` with the standard \`getOrgSdkConfig + unwrapResult\` pattern. The \`resolveOrgAndIssueId\` wrapper (used by \`explain\`/\`plan\`) no longer throws "Organization is required" for bare numeric IDs when the permalink contains the org slug.
+<!-- End lore-managed section -->

src/commands/issue/utils.ts

@@ -9,6 +9,7 @@ import {
   getAutofixState,
   getIssue,
   getIssueByShortId,
+  getIssueInOrg,
   triggerRootCauseAnalysis,
 } from "../../lib/api-client.js";
 import { parseIssueArg } from "../../lib/arg-parsing.js";
@@ -18,7 +19,8 @@ import { ApiError, ContextError, ResolutionError } from "../../lib/errors.js";
 import { getProgressMessage } from "../../lib/formatters/seer.js";
 import { expandToFullShortId, isShortSuffix } from "../../lib/issue-id.js";
 import { poll } from "../../lib/polling.js";
-import { resolveOrgAndProject } from "../../lib/resolve-target.js";
+import { resolveOrg, resolveOrgAndProject } from "../../lib/resolve-target.js";
+import { parseSentryUrl } from "../../lib/sentry-url-parser.js";
 import { isAllDigits } from "../../lib/utils.js";
 import type { SentryIssue, Writer } from "../../types/index.js";
 import { type AutofixState, isTerminalStatus } from "../../types/seer.js";
@@ -240,6 +242,63 @@ export type ResolveIssueOptions = {
   command: string;
 };
 
+/**
+ * Extract the organization slug from a Sentry issue permalink.
+ *
+ * Handles both path-based (`https://sentry.io/organizations/{org}/issues/...`)
+ * and subdomain-style (`https://{org}.sentry.io/issues/...`) SaaS URLs.
+ * Returns undefined if the permalink is missing or not a recognized format.
+ *
+ * @param permalink - Issue permalink URL from the Sentry API response
+ */
+function extractOrgFromPermalink(
+  permalink: string | undefined
+): string | undefined {
+  if (!permalink) {
+    return;
+  }
+  return parseSentryUrl(permalink)?.org;
+}
+
+/**
+ * Resolve a bare numeric issue ID.
+ *
+ * Attempts org-scoped resolution with region routing when org context can be
+ * derived from the working directory (DSN / env vars / config defaults).
+ * Falls back to the legacy unscoped endpoint otherwise.
+ * Extracts the org slug from the response permalink so callers like
+ * {@link resolveOrgAndIssueId} can proceed without explicit org context.
+ */
+async function resolveNumericIssue(
+  id: string,
+  cwd: string,
+  command: string,
+  commandHint: string
+): Promise<ResolvedIssueResult> {
+  const resolvedOrg = await resolveOrg({ cwd });
+  try {
+    const issue = resolvedOrg
+      ? await getIssueInOrg(resolvedOrg.org, id)
+      : await getIssue(id);
+    // Extract org from the response permalink as a fallback so that callers
+    // like resolveOrgAndIssueId (used by explain/plan) get the org slug even
+    // when no org context was available before the fetch.
+    const org = resolvedOrg?.org ?? extractOrgFromPermalink(issue.permalink);
+    return { org, issue };
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 404) {
+      // Improve on the generic "Issue not found" message by including the ID
+      // and suggesting the short-ID format, since users often confuse numeric
+      // group IDs with short-ID suffixes.
+      throw new ResolutionError(`Issue ${id}`, "not found", commandHint, [
+        `No issue with numeric ID ${id} found — you may not have access, or it may have been deleted.`,
+        `If this is a short ID suffix, try: sentry issue ${command} <project>-${id}`,
+      ]);
+    }
+    throw err;
+  }
+}
+
 /**
  * Resolve an issue ID to organization slug and full issue object.
  *
@@ -264,29 +323,8 @@ export async function resolveIssue(
   const commandHint = buildCommandHint(command, issueArg);
 
   switch (parsed.type) {
-    case "numeric": {
-      // Direct fetch by numeric ID - no org context
-      try {
-        const issue = await getIssue(parsed.id);
-        return { org: undefined, issue };
-      } catch (err) {
-        if (err instanceof ApiError && err.status === 404) {
-          // Improve on the generic "Issue not found" message by including the ID
-          // and suggesting the short-ID format, since users often confuse numeric
-          // group IDs with short-ID suffixes.
-          throw new ResolutionError(
-            `Issue ${parsed.id}`,
-            "not found",
-            commandHint,
-            [
-              `No issue with numeric ID ${parsed.id} found — you may not have access, or it may have been deleted.`,
-              `If this is a short ID suffix, try: sentry issue ${command} <project>-${parsed.id}`,
-            ]
-          );
-        }
-        throw err;
-      }
-    }
+    case "numeric":
+      return resolveNumericIssue(parsed.id, cwd, command, commandHint);
 
     case "explicit": {
       // Full context: org + project + suffix
@@ -296,9 +334,9 @@ export async function resolveIssue(
     }
 
     case "explicit-org-numeric": {
-      // Org + numeric ID
+      // Org + numeric ID — use org-scoped endpoint for proper region routing.
       try {
-        const issue = await getIssue(parsed.numericId);
+        const issue = await getIssueInOrg(parsed.org, parsed.numericId);
         return { org: parsed.org, issue };
       } catch (err) {
         if (err instanceof ApiError && err.status === 404) {

src/lib/api-client.ts

@@ -15,6 +15,7 @@ import {
   queryExploreEventsInTableFormat,
   resolveAShortId,
   retrieveAnEventForAProject,
+  retrieveAnIssue,
   retrieveAnIssueEvent,
   retrieveAnOrganization,
   retrieveAProject,
@@ -1118,6 +1119,9 @@ export async function listIssuesAllPages(
 
 /**
  * Get a specific issue by numeric ID.
+ *
+ * Uses the legacy unscoped endpoint — no org context or region routing.
+ * Prefer {@link getIssueInOrg} when the org slug is known.
  */
 export function getIssue(issueId: string): Promise<SentryIssue> {
   // The @sentry/api SDK's retrieveAnIssue requires org slug in path,
@@ -1126,6 +1130,27 @@ export function getIssue(issueId: string): Promise<SentryIssue> {
   return apiRequest<SentryIssue>(`/issues/${issueId}/`);
 }
 
+/**
+ * Get a specific issue by numeric ID, scoped to an organization.
+ *
+ * Uses the org-scoped SDK endpoint with region-aware routing.
+ * Preferred over {@link getIssue} when the org slug is available.
+ *
+ * @param orgSlug - Organization slug (used for region routing)
+ * @param issueId - Numeric issue ID
+ */
+export async function getIssueInOrg(
+  orgSlug: string,
+  issueId: string
+): Promise<SentryIssue> {
+  const config = await getOrgSdkConfig(orgSlug);
+  const result = await retrieveAnIssue({
+    ...config,
+    path: { organization_id_or_slug: orgSlug, issue_id: issueId },
+  });
+  return unwrapResult(result, "Failed to get issue") as unknown as SentryIssue;
+}
+
 /**
  * Get an issue by short ID (e.g., SPOTLIGHT-ELECTRON-4D).
  * Requires organization context to resolve the short ID.

src/lib/sentry-url-parser.ts

@@ -8,6 +8,7 @@
  * so that subsequent API calls reach the correct instance.
  */
 
+import { DEFAULT_SENTRY_HOST } from "./constants.js";
 import { isSentrySaasUrl } from "./sentry-urls.js";
 
 /**
@@ -19,7 +20,7 @@ import { isSentrySaasUrl } from "./sentry-urls.js";
 export type ParsedSentryUrl = {
   /** Scheme + host of the Sentry instance (e.g., "https://sentry.io" or "https://sentry.example.com") */
   baseUrl: string;
-  /** Organization slug from the URL path */
+  /** Organization slug from the URL path or subdomain */
   org: string;
   /** Issue identifier — numeric group ID (e.g., "32886") or short ID (e.g., "CLI-G") */
   issueId?: string;
@@ -83,6 +84,53 @@ function matchSettingsPath(
   return { baseUrl, org: segments[1], project: segments[3] };
 }
 
+/**
+ * Try to extract org from a SaaS subdomain-style URL.
+ *
+ * Matches `https://{org}.sentry.io/issues/{id}/` and similar paths
+ * where the org is in the hostname rather than the URL path.
+ * Only applies to SaaS URLs — self-hosted instances don't use this pattern.
+ *
+ * @returns Parsed result or null if not a subdomain-style SaaS URL with a known path
+ */
+function matchSubdomainOrg(
+  baseUrl: string,
+  hostname: string,
+  segments: string[]
+): ParsedSentryUrl | null {
+  // Must be a subdomain of sentry.io (e.g., "my-org.sentry.io")
+  if (!hostname.endsWith(`.${DEFAULT_SENTRY_HOST}`)) {
+    return null;
+  }
+
+  const org = hostname.slice(0, -`.${DEFAULT_SENTRY_HOST}`.length);
+
+  // Skip region subdomains (us.sentry.io, de.sentry.io, etc.) —
+  // these are API hosts, not org subdomains.
+  if (org.length <= 2) {
+    return null;
+  }
+
+  // /issues/{id}/ (optionally with /events/{eventId}/)
+  if (segments[0] === "issues" && segments[1]) {
+    const eventId =
+      segments[2] === "events" && segments[3] ? segments[3] : undefined;
+    return { baseUrl, org, issueId: segments[1], eventId };
+  }
+
+  // /traces/{traceId}/
+  if (segments[0] === "traces" && segments[1]) {
+    return { baseUrl, org, traceId: segments[1] };
+  }
+
+  // Bare org subdomain URL
+  if (segments.length === 0) {
+    return { baseUrl, org };
+  }
+
+  return null;
+}
+
 /**
  * Parse a Sentry web URL and extract its components.
  *
@@ -93,6 +141,11 @@ function matchSettingsPath(
  * - `/organizations/{org}/traces/{traceId}/`
  * - `/organizations/{org}/`
  *
+ * Also recognizes SaaS subdomain-style URLs:
+ * - `https://{org}.sentry.io/issues/{id}/`
+ * - `https://{org}.sentry.io/traces/{traceId}/`
+ * - `https://{org}.sentry.io/issues/{id}/events/{eventId}/`
+ *
  * @param input - Raw string that may or may not be a URL
  * @returns Parsed components, or null if input is not a recognized Sentry URL
  */
@@ -114,7 +167,8 @@ export function parseSentryUrl(input: string): ParsedSentryUrl | null {
 
   return (
     matchOrganizationsPath(baseUrl, segments) ??
-    matchSettingsPath(baseUrl, segments)
+    matchSettingsPath(baseUrl, segments) ??
+    matchSubdomainOrg(baseUrl, url.hostname, segments)
   );
 }
 

test/commands/issue/utils.test.ts

@@ -110,6 +110,90 @@ describe("resolveOrgAndIssueId", () => {
     ).rejects.toThrow("Organization");
   });
 
+  test("resolves numeric ID when API response includes subdomain-style permalink", async () => {
+    // @ts-expect-error - partial mock
+    globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+      const req = new Request(input, init);
+      const url = req.url;
+
+      if (url.includes("/issues/123456789/")) {
+        return new Response(
+          JSON.stringify({
+            id: "123456789",
+            shortId: "PROJECT-ABC",
+            title: "Test Issue",
+            status: "unresolved",
+            platform: "javascript",
+            type: "error",
+            count: "10",
+            userCount: 5,
+            // Org slug embedded in subdomain-style permalink
+            permalink: "https://my-org.sentry.io/issues/123456789/",
+          }),
+          {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }
+        );
+      }
+
+      return new Response(JSON.stringify({ detail: "Not found" }), {
+        status: 404,
+      });
+    };
+
+    // Org should be extracted from permalink — no longer throws
+    const result = await resolveOrgAndIssueId({
+      issueArg: "123456789",
+      cwd: getConfigDir(),
+      command: "explain",
+    });
+    expect(result.org).toBe("my-org");
+    expect(result.issueId).toBe("123456789");
+  });
+
+  test("resolves numeric ID when API response includes path-style permalink", async () => {
+    // @ts-expect-error - partial mock
+    globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+      const req = new Request(input, init);
+      const url = req.url;
+
+      if (url.includes("/issues/55555555/")) {
+        return new Response(
+          JSON.stringify({
+            id: "55555555",
+            shortId: "BACKEND-XY",
+            title: "Another Issue",
+            status: "unresolved",
+            platform: "python",
+            type: "error",
+            count: "1",
+            userCount: 1,
+            // Path-style permalink (sentry.io/organizations/{org}/issues/{id}/)
+            permalink:
+              "https://sentry.io/organizations/acme-corp/issues/55555555/",
+          }),
+          {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }
+        );
+      }
+
+      return new Response(JSON.stringify({ detail: "Not found" }), {
+        status: 404,
+      });
+    };
+
+    const result = await resolveOrgAndIssueId({
+      issueArg: "55555555",
+      cwd: getConfigDir(),
+      command: "explain",
+    });
+    expect(result.org).toBe("acme-corp");
+    expect(result.issueId).toBe("55555555");
+  });
+
   test("resolves explicit org prefix (org/ISSUE-ID)", async () => {
     // @ts-expect-error - partial mock
     globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
@@ -1271,7 +1355,9 @@ describe("ensureRootCauseAnalysis", () => {
 });
 
 describe("resolveIssue: numeric 404 error handling", () => {
-  const getResolveIssueConfigDir = useTestConfigDir("test-resolve-issue-");
+  const getResolveIssueConfigDir = useTestConfigDir("test-resolve-issue-", {
+    isolateProjectRoot: true,
+  });
 
   let savedFetch: typeof globalThis.fetch;