feat(issue-list): add --period flag, pagination progress, and count abbreviation

- Add --period flag (default 90d) so the CLI matches the UI time window instead of
  the API's implicit 14d default; alias -p
- Show an animated spinner on stderr (⠋⠙⠹… braille frames, 50ms / 20fps) when
  auto-paginating beyond 100 issues, updating with Fetching issues... N/limit;
  suppressed in JSON mode
- Abbreviate large event counts (≥10k) with K/M/B suffixes so the COUNT column
  stays at 5 chars and never causes a layout shift
- Add withProgress<T>() to polling.ts, sharing spinner infrastructure (frames,
  truncation, interval) with the Seer explain/plan commands
- Expose onPage callback in listIssuesAllPages for per-page progress hooks

Author: BYK

src/commands/issue/list.ts

@@ -54,6 +54,7 @@ import {
   type ListCommandMeta,
   type ModeHandler,
 } from "../../lib/org-list.js";
+import { withProgress } from "../../lib/polling.js";
 import {
   type ResolvedTarget,
   resolveAllTargets,
@@ -72,6 +73,7 @@ type ListFlags = {
   readonly query?: string;
   readonly limit: number;
   readonly sort: "date" | "new" | "freq" | "user";
+  readonly period: string;
   readonly json: boolean;
   readonly cursor?: string;
 };
@@ -391,7 +393,13 @@ async function resolveTargetsFromParsedArg(
  */
 async function fetchIssuesForTarget(
   target: ResolvedTarget,
-  options: { query?: string; limit: number; sort: SortValue }
+  options: {
+    query?: string;
+    limit: number;
+    sort: SortValue;
+    statsPeriod?: string;
+    onPage?: (fetched: number, limit: number) => void;
+  }
 ): Promise<FetchResult> {
   try {
     const { issues } = await listIssuesAllPages(
@@ -423,6 +431,9 @@ function nextPageHint(org: string, flags: ListFlags): string {
   if (flags.query) {
     parts.push(`-q "${flags.query}"`);
   }
+  if (flags.period !== "90d") {
+    parts.push(`-t ${flags.period}`);
+  }
   return parts.length > 0 ? `${base} ${parts.join(" ")}` : base;
 }
 
@@ -434,8 +445,9 @@ function nextPageHint(org: string, flags: ListFlags): string {
  */
 async function fetchOrgAllIssues(
   org: string,
-  flags: Pick<ListFlags, "query" | "limit" | "sort">,
-  cursor: string | undefined
+  flags: Pick<ListFlags, "query" | "limit" | "sort" | "period">,
+  cursor: string | undefined,
+  onPage?: (fetched: number, limit: number) => void
 ): Promise<IssuesPage> {
   // When resuming with --cursor, fetch a single page so the cursor chain stays intact.
   if (cursor) {
@@ -445,6 +457,7 @@ async function fetchOrgAllIssues(
       cursor,
       perPage,
       sort: flags.sort,
+      statsPeriod: flags.period,
     });
     return { issues: response.data, nextCursor: response.nextCursor };
   }
@@ -454,13 +467,16 @@ async function fetchOrgAllIssues(
     query: flags.query,
     limit: flags.limit,
     sort: flags.sort,
+    statsPeriod: flags.period,
+    onPage,
   });
   return { issues, nextCursor };
 }
 
 /** Options for {@link handleOrgAllIssues}. */
 type OrgAllIssuesOptions = {
   stdout: Writer;
+  stderr: Writer;
   org: string;
   flags: ListFlags;
   setContext: (orgs: string[], projects: string[]) => void;
@@ -473,7 +489,7 @@ type OrgAllIssuesOptions = {
  * never accidentally reused.
  */
 async function handleOrgAllIssues(options: OrgAllIssuesOptions): Promise<void> {
-  const { stdout, org, flags, setContext } = options;
+  const { stdout, stderr, org, flags, setContext } = options;
   // Encode sort + query in context key so cursors from different searches don't collide.
   const escapedQuery = flags.query
     ? escapeContextKeyValue(flags.query)
@@ -483,7 +499,22 @@ async function handleOrgAllIssues(options: OrgAllIssuesOptions): Promise<void> {
 
   setContext([org], []);
 
-  const { issues, nextCursor } = await fetchOrgAllIssues(org, flags, cursor);
+  const shouldShowProgress = flags.limit > API_MAX_PER_PAGE && !flags.json;
+  const { issues, nextCursor } = await withProgress(
+    {
+      stderr,
+      message: "Fetching issues...",
+      json: !shouldShowProgress,
+    },
+    (setMessage) => {
+      const onPage = shouldShowProgress
+        ? (fetched: number, limit: number) => {
+            setMessage(`Fetching issues... ${fetched}/${limit}`);
+          }
+        : undefined;
+      return fetchOrgAllIssues(org, flags, cursor, onPage);
+    }
+  );
 
   if (nextCursor) {
     setPaginationCursor(PAGINATION_KEY, contextKey, nextCursor);
@@ -574,14 +605,31 @@ async function handleResolvedTargets(
     throw new ContextError("Organization and project", USAGE_HINT);
   }
 
-  const results = await Promise.all(
-    targets.map((t) =>
-      fetchIssuesForTarget(t, {
-        query: flags.query,
-        limit: flags.limit,
-        sort: flags.sort,
-      })
-    )
+  const shouldShowProgress = flags.limit > API_MAX_PER_PAGE && !flags.json;
+  const results = await withProgress(
+    {
+      stderr,
+      message: "Fetching issues...",
+      json: !shouldShowProgress,
+    },
+    (setMessage) => {
+      const onPage = shouldShowProgress
+        ? (fetched: number, limit: number) => {
+            setMessage(`Fetching issues... ${fetched}/${limit}`);
+          }
+        : undefined;
+      return Promise.all(
+        targets.map((t) =>
+          fetchIssuesForTarget(t, {
+            query: flags.query,
+            limit: flags.limit,
+            sort: flags.sort,
+            statsPeriod: flags.period,
+            onPage,
+          })
+        )
+      );
+    }
   );
 
   const validResults: IssueListResult[] = [];
@@ -715,7 +763,9 @@ export const listCommand = buildListCommand("issue", {
       "The --limit flag specifies the number of results to fetch per project (max 1000). " +
       "When the limit exceeds the API page size (100), multiple requests are made " +
       "automatically. Use --cursor to paginate through larger result sets. " +
-      "Note: --cursor resumes from a single page to keep the cursor chain intact.",
+      "Note: --cursor resumes from a single page to keep the cursor chain intact.\n\n" +
+      "By default, only issues with activity in the last 90 days are shown. " +
+      "Use --period to adjust (e.g. --period 24h, --period 14d).",
   },
   parameters: {
     positional: LIST_TARGET_POSITIONAL,
@@ -733,6 +783,12 @@ export const listCommand = buildListCommand("issue", {
         brief: "Sort by: date, new, freq, user",
         default: "date" as const,
       },
+      period: {
+        kind: "parsed",
+        parse: String,
+        brief: "Time period for issue activity (e.g. 24h, 14d, 90d)",
+        default: "90d",
+      },
       json: LIST_JSON_FLAG,
       cursor: {
         kind: "parsed",
@@ -757,7 +813,7 @@ export const listCommand = buildListCommand("issue", {
         optional: true,
       },
     },
-    aliases: { ...LIST_BASE_ALIASES, q: "query", s: "sort" },
+    aliases: { ...LIST_BASE_ALIASES, q: "query", s: "sort", t: "period" },
   },
   async func(
     this: SentryContext,
@@ -799,6 +855,7 @@ export const listCommand = buildListCommand("issue", {
         "org-all": (ctx) =>
           handleOrgAllIssues({
             stdout: ctx.stdout,
+            stderr,
             org: ctx.parsed.org,
             flags,
             setContext,

src/lib/api-client.ts

@@ -1071,6 +1071,8 @@ export async function listIssuesAllPages(
     limit: number;
     sort?: "date" | "new" | "freq" | "user";
     statsPeriod?: string;
+    /** Called after each page is fetched. Useful for progress indicators. */
+    onPage?: (fetched: number, limit: number) => void;
   }
 ): Promise<IssuesPage> {
   if (options.limit < 1) {
@@ -1095,6 +1097,7 @@ export async function listIssuesAllPages(
     });
 
     allResults.push(...response.data);
+    options.onPage?.(allResults.length, options.limit);
 
     // Stop if we've reached the requested limit or there are no more pages
     if (allResults.length >= options.limit || !response.nextCursor) {

src/lib/formatters/human.ts

@@ -313,6 +313,28 @@ const COL_SEEN = 10;
 /** Width for the FIXABILITY column (longest value "high(100%)" = 10) */
 const COL_FIX = 10;
 
+/**
+ * Abbreviate large numbers to fit within {@link COL_COUNT} characters.
+ * Uses K/M/B suffixes for thousands/millions/billions.
+ *
+ * Examples: 999 → "999", 1200 → "1.2K", 15000 → " 15K", 1500000 → "1.5M"
+ */
+function abbreviateCount(raw: string): string {
+  const n = Number(raw);
+  if (Number.isNaN(n) || n < 10_000) {
+    return raw.padStart(COL_COUNT);
+  }
+  let abbreviated: string;
+  if (n >= 1_000_000_000) {
+    abbreviated = `${(n / 1_000_000_000).toFixed(n >= 10_000_000_000 ? 0 : 1)}B`;
+  } else if (n >= 1_000_000) {
+    abbreviated = `${(n / 1_000_000).toFixed(n >= 10_000_000 ? 0 : 1)}M`;
+  } else {
+    abbreviated = `${(n / 1000).toFixed(n >= 100_000 ? 0 : 1)}K`;
+  }
+  return abbreviated.padStart(COL_COUNT);
+}
+
 /** Column where title starts in single-project mode (no ALIAS column) */
 const TITLE_START_COL =
   COL_LEVEL + 1 + COL_SHORT_ID + 1 + COL_COUNT + 2 + COL_SEEN + 2 + COL_FIX + 2;
@@ -582,7 +604,7 @@ export function formatIssueRow(
   const rawLen = getShortIdDisplayLength(issue.shortId);
   const shortIdPadding = " ".repeat(Math.max(0, COL_SHORT_ID - rawLen));
   const shortId = `${formattedShortId}${shortIdPadding}`;
-  const count = `${issue.count}`.padStart(COL_COUNT);
+  const count = abbreviateCount(`${issue.count}`);
   const seen = formatRelativeTime(issue.lastSeen);
 
   // Fixability column (color applied after padding to preserve alignment)

src/lib/polling.ts

@@ -14,8 +14,8 @@ import {
 /** Default polling interval in milliseconds */
 const DEFAULT_POLL_INTERVAL_MS = 1000;
 
-/** Animation interval for spinner updates (independent of polling) */
-const ANIMATION_INTERVAL_MS = 80;
+/** Animation interval for spinner updates — 50ms gives 20fps, matching the ora/inquirer standard */
+const ANIMATION_INTERVAL_MS = 50;
 
 /** Default timeout in milliseconds (6 minutes) */
 const DEFAULT_TIMEOUT_MS = 360_000;
@@ -49,7 +49,7 @@ export type PollOptions<T> = {
  *
  * Polls the fetchState function until shouldStop returns true or timeout is reached.
  * Displays an animated spinner with progress messages when not in JSON mode.
- * Animation runs at 80ms intervals independently of polling frequency.
+ * Animation runs at 50ms intervals (20fps) independently of polling frequency.
  *
  * @typeParam T - The type of state being polled
  * @param options - Polling configuration
@@ -121,3 +121,71 @@ export async function poll<T>(options: PollOptions<T>): Promise<T> {
     }
   }
 }
+
+/**
+ * Options for {@link withProgress}.
+ */
+export type WithProgressOptions = {
+  /** Output stream for progress */
+  stderr: Writer;
+  /** Initial spinner message */
+  message: string;
+  /** Suppress progress output (JSON mode) */
+  json?: boolean;
+};
+
+/**
+ * Run an async operation with an animated spinner on stderr.
+ *
+ * The spinner uses the same braille frames as the Seer polling spinner,
+ * giving a consistent look across all CLI commands.
+ *
+ * The callback receives a `setMessage` function to update the displayed
+ * message as work progresses (e.g. to show page counts during pagination).
+ * Progress is automatically cleared when the operation completes.
+ *
+ * @param options - Spinner configuration
+ * @param fn - Async operation to run; receives `setMessage` to update the displayed text
+ * @returns The value returned by `fn`
+ *
+ * @example
+ * ```typescript
+ * const result = await withProgress(
+ *   { stderr, message: "Fetching issues...", json },
+ *   async (setMessage) => {
+ *     const data = await fetchWithPages({
+ *       onPage: (fetched, total) => setMessage(`Fetching issues... ${fetched}/${total}`),
+ *     });
+ *     return data;
+ *   }
+ * );
+ * ```
+ */
+export async function withProgress<T>(
+  options: WithProgressOptions,
+  fn: (setMessage: (msg: string) => void) => Promise<T>
+): Promise<T> {
+  const { stderr, json = false } = options;
+  let currentMessage = options.message;
+  let tick = 0;
+
+  let animationTimer: Timer | undefined;
+  if (!json) {
+    animationTimer = setInterval(() => {
+      const display = truncateProgressMessage(currentMessage);
+      stderr.write(`\r\x1b[K${formatProgressLine(display, tick)}`);
+      tick += 1;
+    }, ANIMATION_INTERVAL_MS);
+  }
+
+  try {
+    return await fn((msg) => {
+      currentMessage = msg;
+    });
+  } finally {
+    if (animationTimer) {
+      clearInterval(animationTimer);
+      stderr.write("\r\x1b[K");
+    }
+  }
+}