fix(polling): throw TimeoutError instead of bare Error on timeout (#503)

Replace the generic `new Error(timeoutMessage)` in `poll()` with a
structured
`TimeoutError` (extends `CliError`) that carries an optional `hint`
field. This gives
the CLI error handler richer context to display actionable suggestions
when a polling
operation times out.

## Changes

- **`src/lib/errors.ts`** — Add `TimeoutError` class with optional
`hint` and `format()` override
- **`src/lib/polling.ts`** — Throw `TimeoutError` instead of bare
`Error`; add `timeoutHint` option to `PollOptions`
- **`src/lib/sentry-urls.ts`** — Add `buildIssueUrl()` helper (SaaS +
self-hosted)
- **`src/commands/issue/utils.ts`** — `pollAutofixState` passes a hint
with the issue URL and retry command
- **`test/lib/polling.property.test.ts`** — Assert `TimeoutError` type
and verify hint propagation

## Context

Addresses [CLI-J0](https://sentry.sentry.io/issues/7350074690/) — a user
hit the
6-minute Seer analysis timeout via `sentry issue explain`. The timeout
itself is
expected (the backend can be slow), but the bare `Error` gave no
guidance on what
to do next. Now the user sees:

```
Error: Operation timed out after 6 minutes. Try again or check the issue in Sentry web UI.

The analysis may still complete in the background.
  View in Sentry: https://my-org.sentry.io/issues/12345/
  Or retry:       sentry issue explain 12345
```

Author: BYK

src/commands/issue/plan.ts

@@ -247,6 +247,9 @@ export const planCommand = buildCommand({
         json: flags.json,
         timeoutMessage:
           "Plan creation timed out after 6 minutes. Try again or check the issue in Sentry web UI.",
+        timeoutHint:
+          "The plan may still be generated in the background.\n" +
+          `  Or retry: sentry issue plan ${issueArg}`,
       });
 
       // Handle errors

src/commands/issue/utils.ts

@@ -39,6 +39,7 @@ import {
   resolveOrgAndProject,
 } from "../../lib/resolve-target.js";
 import { parseSentryUrl } from "../../lib/sentry-url-parser.js";
+import { buildIssueUrl } from "../../lib/sentry-urls.js";
 import { isAllDigits } from "../../lib/utils.js";
 import type { SentryIssue } from "../../types/index.js";
 import { type AutofixState, isTerminalStatus } from "../../types/seer.js";
@@ -624,6 +625,9 @@ type PollAutofixOptions = {
   timeoutMs?: number;
   /** Custom timeout error message */
   timeoutMessage?: string;
+  /** Actionable hint appended to the TimeoutError (e.g., "Run the command again…").
+   *  When omitted, defaults to a hint with the Sentry issue URL. */
+  timeoutHint?: string;
   /** Stop polling when status is WAITING_FOR_USER_RESPONSE (default: false) */
   stopOnWaitingForUser?: boolean;
 };
@@ -729,9 +733,17 @@ export async function pollAutofixState(
     pollIntervalMs,
     timeoutMs = DEFAULT_TIMEOUT_MS,
     timeoutMessage = "Operation timed out after 6 minutes. Try again or check the issue in Sentry web UI.",
+    timeoutHint,
     stopOnWaitingForUser = false,
   } = options;
 
+  const issueUrl = buildIssueUrl(orgSlug, issueId);
+  const hint =
+    timeoutHint ??
+    "The analysis may still complete in the background.\n" +
+      `  View in Sentry: ${issueUrl}\n` +
+      `  Or retry:       sentry issue explain ${issueId}`;
+
   return await poll<AutofixState>({
     fetchState: () => getAutofixState(orgSlug, issueId),
     shouldStop: (state) => shouldStopPolling(state, stopOnWaitingForUser),
@@ -740,6 +752,7 @@ export async function pollAutofixState(
     pollIntervalMs,
     timeoutMs,
     timeoutMessage,
+    timeoutHint: hint,
     initialMessage: "Waiting for analysis to start...",
   });
 }

src/lib/errors.ts

@@ -433,6 +433,33 @@ export class SeerError extends CliError {
   }
 }
 
+/**
+ * Timeout errors for long-running polling operations.
+ *
+ * Use when a polling loop exceeds its time budget. Provides structured
+ * hints so the user knows the operation may still complete in the background.
+ *
+ * @param message - What timed out (e.g., "Operation timed out after 6 minutes.")
+ * @param hint - Actionable suggestion (e.g., "Run the command again — the analysis may finish in the background.")
+ */
+export class TimeoutError extends CliError {
+  readonly hint?: string;
+
+  constructor(message: string, hint?: string) {
+    super(message);
+    this.name = "TimeoutError";
+    this.hint = hint;
+  }
+
+  override format(): string {
+    let msg = this.message;
+    if (this.hint) {
+      msg += `\n\n${this.hint}`;
+    }
+    return msg;
+  }
+}
+
 // Error Utilities
 
 /**

src/lib/polling.ts

@@ -5,6 +5,7 @@
  * Used by commands that need to wait for async operations to complete.
  */
 
+import { TimeoutError } from "./errors.js";
 import {
   formatProgressLine,
   truncateProgressMessage,
@@ -37,6 +38,8 @@ export type PollOptions<T> = {
   timeoutMs?: number;
   /** Custom timeout message */
   timeoutMessage?: string;
+  /** Actionable hint appended to the TimeoutError (e.g., "Run the command again…") */
+  timeoutHint?: string;
   /** Initial progress message */
   initialMessage?: string;
 };
@@ -51,7 +54,7 @@ export type PollOptions<T> = {
  * @typeParam T - The type of state being polled
  * @param options - Polling configuration
  * @returns The final state when shouldStop returns true
- * @throws {Error} When timeout is reached before shouldStop returns true
+ * @throws {TimeoutError} When timeout is reached before shouldStop returns true
  *
  * @example
  * ```typescript
@@ -74,6 +77,7 @@ export async function poll<T>(options: PollOptions<T>): Promise<T> {
     pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
     timeoutMs = DEFAULT_TIMEOUT_MS,
     timeoutMessage = "Operation timed out after 6 minutes. Try again or check the Sentry web UI.",
+    timeoutHint,
     initialMessage = "Waiting for operation to start...",
   } = options;
 
@@ -98,7 +102,7 @@ export async function poll<T>(options: PollOptions<T>): Promise<T> {
       await Bun.sleep(pollIntervalMs);
     }
 
-    throw new Error(timeoutMessage);
+    throw new TimeoutError(timeoutMessage, timeoutHint);
   } finally {
     spinner?.stop();
     if (!json) {

src/lib/sentry-urls.ts

@@ -88,6 +88,20 @@ export function buildProjectUrl(orgSlug: string, projectSlug: string): string {
   return `${getSentryBaseUrl()}/settings/${orgSlug}/projects/${projectSlug}/`;
 }
 
+/**
+ * Build URL to view an issue in Sentry.
+ *
+ * @param orgSlug - Organization slug
+ * @param issueId - Numeric issue ID
+ * @returns Full URL to the issue detail page
+ */
+export function buildIssueUrl(orgSlug: string, issueId: string): string {
+  if (isSaaS()) {
+    return `${getOrgBaseUrl(orgSlug)}/issues/${issueId}/`;
+  }
+  return `${getSentryBaseUrl()}/organizations/${orgSlug}/issues/${issueId}/`;
+}
+
 /**
  * Build URL to search for an event in Sentry.
  * Uses the issues search with event.id filter.

test/lib/polling.property.test.ts

@@ -13,6 +13,7 @@ import {
   integer,
   nat,
 } from "fast-check";
+import { TimeoutError } from "../../src/lib/errors.js";
 import { poll } from "../../src/lib/polling.js";
 import { DEFAULT_NUM_RUNS } from "../model-based/helpers.js";
 
@@ -70,28 +71,55 @@ describe("poll properties", () => {
     );
   });
 
-  test("throws timeout error when shouldStop never returns true", async () => {
+  test("throws TimeoutError when shouldStop never returns true", async () => {
     await fcAssert(
       asyncProperty(nat(50), async (stateValue) => {
         const timeoutMs = 50; // Very short timeout for testing
         const customMessage = `Custom timeout: ${stateValue}`;
 
-        await expect(
-          poll({
+        try {
+          await poll({
             fetchState: async () => ({ value: stateValue }),
             shouldStop: () => false, // Never stop
             getProgressMessage: () => "Testing...",
             json: true,
             pollIntervalMs: 10,
             timeoutMs,
             timeoutMessage: customMessage,
-          })
-        ).rejects.toThrow(customMessage);
+          });
+          // Should not reach here
+          expect.unreachable("Expected TimeoutError to be thrown");
+        } catch (error) {
+          expect(error).toBeInstanceOf(TimeoutError);
+          expect((error as TimeoutError).message).toBe(customMessage);
+        }
       }),
       { numRuns: Math.min(DEFAULT_NUM_RUNS, 20) } // Fewer runs since timeout tests are slow
     );
   });
 
+  test("TimeoutError includes hint when provided", async () => {
+    const customHint = "Try running the command again.";
+
+    try {
+      await poll({
+        fetchState: async () => ({ value: 1 }),
+        shouldStop: () => false,
+        getProgressMessage: () => "Testing...",
+        json: true,
+        pollIntervalMs: 10,
+        timeoutMs: 50,
+        timeoutHint: customHint,
+      });
+      expect.unreachable("Expected TimeoutError to be thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(TimeoutError);
+      const te = error as TimeoutError;
+      expect(te.hint).toBe(customHint);
+      expect(te.format()).toContain(customHint);
+    }
+  });
+
   test("fetchState call count is bounded by timeout/interval", async () => {
     await fcAssert(
       asyncProperty(
@@ -200,7 +228,7 @@ describe("poll properties", () => {
 
 describe("poll edge cases", () => {
   test("handles immediate timeout (timeoutMs = 0)", async () => {
-    // With 0 timeout, should throw immediately or after first fetch
+    // With 0 timeout, should throw TimeoutError immediately or after first fetch
     await expect(
       poll({
         fetchState: async () => ({ value: 1 }),
@@ -210,7 +238,7 @@ describe("poll edge cases", () => {
         pollIntervalMs: 10,
         timeoutMs: 0,
       })
-    ).rejects.toThrow();
+    ).rejects.toBeInstanceOf(TimeoutError);
   });
 
   test("handles fetchState throwing errors", async () => {