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

.opencode/plans/part4-numeric-issue-resolution.md

@@ -0,0 +1,123 @@
+# Part 4: Improve Numeric Issue ID Resolution
+
+## Problem
+
+When a user runs `sentry issue view 99124558` (bare numeric ID):
+
+1. The unscoped `GET /api/0/issues/{id}/` call succeeds and returns the full issue object — including a `permalink` field that contains the org slug — but `resolveIssue` discards it and returns `org: undefined`.
+2. `explain` and `plan` commands call `resolveOrgAndIssueId`, which then throws `ContextError("Organization", ...)` — even though the issue was found.
+3. For `sentry issue view myorg/99124558`, the org is available but the API call is still unscoped (no region routing) — misleading error messages and wrong region.
+4. The `parseSentryUrl` utility doesn't handle subdomain-style permalinks (`https://my-org.sentry.io/issues/99124558/`), only the path-based format (`https://sentry.io/organizations/my-org/issues/99124558/`).
+
+## Five-part fix (A–E)
+
+### E — Fix `parseSentryUrl` for subdomain-style permalinks
+
+**File**: `src/lib/sentry-url-parser.ts`
+
+Add `matchSubdomainOrg()` helper and call it as final fallback in `parseSentryUrl`:
+
+```
+https://my-org.sentry.io/issues/99124558/  →  org="my-org", issueId="99124558"
+https://my-org.sentry.io/traces/abc.../   →  org="my-org", traceId="abc..."
+```
+
+Rules:
+- Only applies to hostnames ending in `.sentry.io`
+- Skip 2-char subdomains (`us`, `de`) — those are API region hosts, not orgs
+- Import `DEFAULT_SENTRY_HOST` from `./constants.js`
+
+### B — Add `getIssueInOrg(orgSlug, issueId)` to api-client.ts
+
+**File**: `src/lib/api-client.ts`
+
+New exported function using the SDK's `retrieveAnIssue` (already exported by `@sentry/api`) with region routing via `getOrgSdkConfig`, following the same pattern as `getIssueByShortId`:
+
+```typescript
+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;
+}
+```
+
+Add `retrieveAnIssue` to the SDK import at the top of the file.
+
+### C — Use org-scoped fetch in `explicit-org-numeric` case
+
+**File**: `src/commands/issue/utils.ts`, `explicit-org-numeric` case (~line 298)
+
+Change `getIssue(parsed.numericId)` → `getIssueInOrg(parsed.org, parsed.numericId)`.
+Import `getIssueInOrg` from api-client.
+
+This gives correct region routing and honest error messages ("not found in org X" actually scoped to org X).
+
+### D — Proactive org resolution for bare `numeric` case
+
+**File**: `src/commands/issue/utils.ts`, `numeric` case (~line 267)
+
+Before falling back to unscoped `getIssue`, try `resolveOrg({ cwd })`:
+- If org found: use `getIssueInOrg(org, id)` for region-aware fetch
+- If no org: fall back to unscoped `getIssue(id)` (preserves existing behaviour)
+
+Import `resolveOrg` from `../../lib/resolve-target.js`.
+
+```typescript
+case "numeric": {
+  // Try to resolve org from context (DSN/env/config defaults)
+  const resolved = await resolveOrg({ cwd });
+  try {
+    const issue = resolved
+      ? await getIssueInOrg(resolved.org, parsed.id)
+      : await getIssue(parsed.id);
+    const org = resolved?.org ?? extractOrgFromPermalink(issue.permalink);
+    return { org, issue };
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 404) {
+      throw new ResolutionError(...);
+    }
+    throw err;
+  }
+}
+```
+
+### A — Extract org from `issue.permalink` as fallback
+
+**File**: `src/commands/issue/utils.ts`
+
+Add a small internal helper `extractOrgFromPermalink(permalink?: string): string | undefined` that calls `parseSentryUrl` and returns the `org` field.
+
+Use this in:
+1. The `numeric` case (when unscoped fetch succeeds but org is still undefined after D above)
+2. The `explicit-org-numeric` case (use `parsed.org` as primary, permalink as fallback validation — not strictly necessary but consistent)
+
+## Files to modify
+
+| File | Changes |
+|------|---------|
+| `src/lib/sentry-url-parser.ts` | Add `matchSubdomainOrg`, update `parseSentryUrl`, update JSDoc, add `DEFAULT_SENTRY_HOST` import |
+| `src/lib/api-client.ts` | Add `retrieveAnIssue` to SDK import; add `getIssueInOrg` after `getIssue` |
+| `src/commands/issue/utils.ts` | Import `getIssueInOrg`, `resolveOrg`; add `extractOrgFromPermalink` helper; update `numeric` and `explicit-org-numeric` cases |
+
+## Tests to add/update
+
+| File | What |
+|------|------|
+| `test/lib/sentry-url-parser.test.ts` | New tests for subdomain-style URLs (`my-org.sentry.io`) |
+| `test/lib/api-client.test.ts` (or new) | Unit test for `getIssueInOrg` |
+| `test/commands/issue/utils.test.ts` | Update `numeric` case: org should now be populated from permalink; update `explicit-org-numeric` case |
+
+## What changes for the user
+
+| Scenario | Before | After |
+|----------|--------|-------|
+| `sentry issue view 99124558` (found) | Works, no org in output | Works, org resolved from permalink |
+| `sentry issue explain 99124558` | Fails: "Organization is required" | Works: org extracted from permalink |
+| `sentry issue view myorg/99124558` | Unscoped API call, wrong region possible | Org-scoped call with correct region routing |
+| `sentry issue view 99124558` in project dir | No DSN fallback | Tries DSN/env/config first, uses org-scoped call |

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.