feat: magic @ selectors (@latest, @most_frequent) for issue commands

Add magic `@` selectors that resolve to issues dynamically:
- `@latest` → issue with most recent `lastSeen` timestamp
- `@most_frequent` → issue with highest event frequency

Supports bare selectors (`@latest`) and org-prefixed
(`sentry/@latest`). Case-insensitive with alternative spellings
(`@mostfrequent`, `@most-frequent`).

Works with all issue commands: `issue view`, `issue explain`,
`issue plan`.

Fixes #45

Author: BYK

AGENTS.md

@@ -629,11 +629,17 @@ mock.module("./some-module", () => ({
 ### Architecture
 
 <!-- lore:019cbeba-e4d3-748c-ad50-fe3c3d5c0a0d -->
-* **Auth token env var override pattern: SENTRY\_AUTH\_TOKEN > SENTRY\_TOKEN > SQLite**: Authentication in \`src/lib/db/auth.ts\` follows layered precedence: \`SENTRY\_AUTH\_TOKEN\` env var > \`SENTRY\_TOKEN\` env var > SQLite-stored OAuth token. \`getEnvToken()\` reads env vars with \`.trim()\` (empty/whitespace = unset). \`AuthSource\` type tracks provenance: \`"env:SENTRY\_AUTH\_TOKEN"\` | \`"env:SENTRY\_TOKEN"\` | \`"oauth"\`. \`ENV\_SOURCE\_PREFIX = "env:"\` constant is used for parsing source strings (use \`.length\` not hardcoded 4). \`getActiveEnvVarName()\` is the shared helper for commands needing the env var name — calls \`getEnvToken()\` directly (no DB fallback). Env tokens bypass all refresh/expiry logic. \`isEnvTokenActive()\` is the guard for auth commands. Logout must NOT clear stored auth when env token active — just inform user to unset the env var. \`getEnvToken\`/\`isEnvTokenActive\` stay in \`db/auth.ts\` despite not touching DB, because they're tightly coupled with \`getAuthToken\`/\`getAuthConfig\`/\`refreshToken\`.
+* **Auth token env var override pattern: SENTRY\_AUTH\_TOKEN > SENTRY\_TOKEN > SQLite**: Auth in \`src/lib/db/auth.ts\` follows layered precedence: \`SENTRY\_AUTH\_TOKEN\` > \`SENTRY\_TOKEN\` > SQLite OAuth token. \`getEnvToken()\` trims env vars (empty/whitespace = unset). \`AuthSource\` tracks provenance. \`ENV\_SOURCE\_PREFIX = "env:"\` — use \`.length\` not hardcoded 4. Env tokens bypass refresh/expiry. \`isEnvTokenActive()\` guards auth commands. Logout must NOT clear stored auth when env token active. These functions stay in \`db/auth.ts\` despite not touching DB because they're tightly coupled with token retrieval.
 
 <!-- lore:019cbaa2-e4a2-76c0-8f64-917a97ae20c5 -->
 * **Consola chosen as CLI logger with Sentry createConsolaReporter integration**: Consola is the CLI logger with Sentry createConsolaReporter integration. Two reporters: FancyReporter (stderr) + Sentry structured logs. Level via \`SENTRY\_LOG\_LEVEL\`: error=0, warn=1, info=3, debug=4, trace=5. \`buildCommand\` in \`src/lib/command.ts\` injects hidden \`--log-level\`/\`--verbose\` flags, strips before calling handler. \`withTag()\` creates independent instances; \`setLogLevel()\` propagates via registry. All user-facing output must use consola, not raw stderr. HandlerContext intentionally omits stderr.
 
+<!-- lore:019cce8d-f2c5-726e-8a04-3f48caba45ec -->
+* **Input validation layer: src/lib/input-validation.ts guards CLI arg parsing**: Four validators in \`src/lib/input-validation.ts\` guard against agent-hallucinated inputs: \`rejectControlChars\` (ASCII < 0x20), \`rejectPreEncoded\` (%XX), \`validateResourceId\` (rejects ?, #, %, whitespace), \`validateEndpoint\` (rejects \`..\` traversal). Applied in \`parseSlashOrgProject\`, bare-slug path in \`parseOrgProjectArg\`, \`parseIssueArg\`, and \`normalizeEndpoint\` (api.ts). NOT applied in \`parseSlashSeparatedArg\` for no-slash plain IDs — those may contain structural separators (newlines for log view batch IDs) that callers split downstream. Validation targets user-facing parse boundaries only; env vars and DB cache values are trusted.
+
+<!-- lore:019cd2d1-aa47-7fc1-92f9-cc6c49b19460 -->
+* **Magic @ selectors resolve issues dynamically via sort-based list API queries**: Magic \`@\` selectors (\`@latest\`, \`@most\_frequent\`) in \`parseIssueArg\` are detected early (before \`validateResourceId\`) because \`@\` is not in the forbidden charset. \`SELECTOR\_MAP\` provides case-insensitive matching with common variations (\`@mostfrequent\`, \`@most-frequent\`). Resolution in \`resolveSelector\` (issue/utils.ts) maps selectors to \`IssueSort\` values (\`date\`, \`freq\`), calls \`listIssuesPaginated\` with \`perPage: 1\` and \`query: 'is:unresolved'\`. Supports org-prefixed form: \`sentry/@latest\`. Unrecognized \`@\`-prefixed strings fall through to suffix-only parsing (not an error). The \`ParsedIssueArg\` union includes \`{ type: 'selector'; selector: IssueSelector; org?: string }\`.
+
 ### Gotcha
 
 <!-- lore:019cc484-f0e1-7016-a851-177fb9ad2cc4 -->
@@ -642,12 +648,6 @@ mock.module("./some-module", () => ({
 <!-- lore:019cc40e-e56e-71e9-bc5d-545f97df732b -->
 * **Consola prompt cancel returns truthy Symbol, not false**: When a user cancels a \`consola\` / \`@clack/prompts\` confirmation prompt (Ctrl+C), the return value is \`Symbol(clack:cancel)\`, not \`false\`. Since Symbols are truthy in JavaScript, checking \`!confirmed\` will be \`false\` and the code falls through as if the user confirmed. Fix: use \`confirmed !== true\` (strict equality) instead of \`!confirmed\` to correctly handle cancel, false, and any other non-true values.
 
-<!-- lore:019cc484-f0e7-7a64-bea1-f3f98e9c56c1 -->
-* **Craft v2 GitHub App must be installed per-repo**: The Craft v2 release/publish workflows use \`actions/create-github-app-token@v1\` which requires the GitHub App to be installed on the specific repository. If the app is configured for "Only select repositories", adding a new repo to the Craft pipeline requires manually adding it at GitHub Settings → Installations → \[App] → Configure. The \`APP\_ID\` variable and \`APP\_PRIVATE\_KEY\` secret are set in the \`production\` environment, not at repo level. Symptom: 404 on \`GET /repos/{owner}/{repo}/installation\`.
-
-<!-- lore:019cc303-e399-7390-a693-46b68354c15f -->
-* **Sentry.setContext persists on scope — stale data across retries**: \`Sentry.setContext(key, data)\` sets context on the current scope and persists until overwritten. In retry/polling loops (e.g., follow mode), if an error sets diagnostic context and a subsequent iteration succeeds, the stale context remains attached to future events from that scope. Low severity for one-shot throw-on-failure patterns like \`apiRequestToRegion\`, but worth noting for long-lived scopes with intermittent failures.
-
 <!-- lore:019cbe0d-d03e-716c-b372-b09998c07ed6 -->
 * **Stricli rejects unknown flags — pre-parsed global flags must be consumed from argv**: Stricli's arg parser is strict: any \`--flag\` not registered on a command throws \`No flag registered for --flag\`. Global flags (parsed before Stricli in bin.ts) MUST be spliced out of argv. \`--log-level\` was correctly consumed but \`--verbose\` was intentionally left in (for the \`api\` command's own \`--verbose\`). This breaks every other command. Also, \`argv.indexOf('--flag')\` doesn't match \`--flag=value\` form — must check both space-separated and equals-sign forms when pre-parsing. A Biome \`noRestrictedImports\` lint rule in \`biome.jsonc\` now blocks \`import { buildCommand } from "@stricli/core"\` at error level — only \`src/lib/command.ts\` is exempted. Other \`@stricli/core\` exports (\`buildRouteMap\`, \`run\`, etc.) are allowed.
 
@@ -656,6 +656,9 @@ mock.module("./some-module", () => ({
 
 ### Pattern
 
+<!-- lore:019cce8d-f2d6-7862-9105-7a0048f0e993 -->
+* **Property-based tests for input validators use stringMatching for forbidden char coverage**: In \`test/lib/input-validation.property.test.ts\`, forbidden-character arbitraries are built with \`stringMatching\` targeting specific regex patterns (e.g., \`/^\[^\x00-\x1f]\*\[\x00-\x1f]\[^\x00-\x1f]\*$/\` for control chars). This ensures fast-check generates strings that always contain the forbidden character while varying surrounding content. The \`biome-ignore lint/suspicious/noControlCharactersInRegex\` suppression is needed on the control char regex constant in \`input-validation.ts\`.
+
 <!-- lore:019cbe44-7687-7288-81a2-662feefc28ea -->
 * **SKILL.md generator must filter hidden Stricli flags**: \`script/generate-skill.ts\` introspects Stricli's route tree to auto-generate \`plugins/sentry-cli/skills/sentry-cli/SKILL.md\`. The \`FlagDef\` type must include \`hidden?: boolean\` and \`extractFlags\` must propagate it to \`FlagInfo\`. The filter in \`generateCommandDoc\` must exclude \`f.hidden\` alongside \`help\`/\`helpAll\`. Without this, hidden flags injected by \`buildCommand\` (like \`--log-level\`, \`--verbose\`) appear on every command in the AI agent skill file. Global flags should instead be documented once in \`docs/src/content/docs/commands/index.md\` Global Options section, which the generator pulls into SKILL.md via \`loadCommandsOverview\`.
 <!-- End lore-managed section -->

src/commands/issue/explain.ts

@@ -42,12 +42,16 @@ export const explainCommand = buildCommand({
       "The analysis may take a few minutes for new issues.\n" +
       "Use --force to trigger a fresh analysis even if one already exists.\n\n" +
       "Issue formats:\n" +
-      "  <org>/ID       - Explicit org: sentry/EXTENSION-7, sentry/cli-G\n" +
+      "  @latest          - Most recent unresolved issue\n" +
+      "  @most_frequent   - Issue with highest event frequency\n" +
+      "  <org>/ID         - Explicit org: sentry/EXTENSION-7, sentry/cli-G\n" +
+      "  <org>/@selector  - Selector with org: my-org/@latest\n" +
       "  <project>-suffix - Project + suffix: cli-G, spotlight-electron-4Y\n" +
-      "  ID             - Short ID: CLI-G (searches across orgs)\n" +
-      "  suffix         - Suffix only: G (requires DSN context)\n" +
-      "  numeric        - Numeric ID: 123456789\n\n" +
+      "  ID               - Short ID: CLI-G (searches across orgs)\n" +
+      "  suffix           - Suffix only: G (requires DSN context)\n" +
+      "  numeric          - Numeric ID: 123456789\n\n" +
       "Examples:\n" +
+      "  sentry issue explain @latest\n" +
       "  sentry issue explain 123456789\n" +
       "  sentry issue explain sentry/EXTENSION-7\n" +
       "  sentry issue explain cli-G\n" +

src/commands/issue/index.ts

@@ -19,7 +19,14 @@ export const issueRoute = buildRouteMap({
       "  list     List issues in a project\n" +
       "  view     View details of a specific issue\n" +
       "  explain  Analyze an issue using Seer AI\n" +
-      "  plan     Generate a solution plan using Seer AI",
+      "  plan     Generate a solution plan using Seer AI\n\n" +
+      "Magic selectors (available for view, explain, plan):\n" +
+      "  @latest          Most recent unresolved issue\n" +
+      "  @most_frequent   Issue with the highest event frequency\n\n" +
+      "Examples:\n" +
+      "  sentry issue view @latest\n" +
+      "  sentry issue explain @most_frequent\n" +
+      "  sentry issue plan my-org/@latest",
     hideRoute: {},
   },
 });

src/commands/issue/plan.ts

@@ -147,15 +147,19 @@ export const planCommand = buildCommand({
       "If multiple root causes are identified, use --cause to specify which one.\n" +
       "Use --force to regenerate a plan even if one already exists.\n\n" +
       "Issue formats:\n" +
-      "  <org>/ID       - Explicit org: sentry/EXTENSION-7, sentry/cli-G\n" +
+      "  @latest          - Most recent unresolved issue\n" +
+      "  @most_frequent   - Issue with highest event frequency\n" +
+      "  <org>/ID         - Explicit org: sentry/EXTENSION-7, sentry/cli-G\n" +
+      "  <org>/@selector  - Selector with org: my-org/@latest\n" +
       "  <project>-suffix - Project + suffix: cli-G, spotlight-electron-4Y\n" +
-      "  ID             - Short ID: CLI-G (searches across orgs)\n" +
-      "  suffix         - Suffix only: G (requires DSN context)\n" +
-      "  numeric        - Numeric ID: 123456789\n\n" +
+      "  ID               - Short ID: CLI-G (searches across orgs)\n" +
+      "  suffix           - Suffix only: G (requires DSN context)\n" +
+      "  numeric          - Numeric ID: 123456789\n\n" +
       "Prerequisites:\n" +
       "  - GitHub integration configured for your organization\n" +
       "  - Code mappings set up for your project\n\n" +
       "Examples:\n" +
+      "  sentry issue plan @latest --cause 0\n" +
       "  sentry issue plan 123456789 --cause 0\n" +
       "  sentry issue plan sentry/EXTENSION-7 --cause 1\n" +
       "  sentry issue plan cli-G --cause 0\n" +

src/commands/issue/utils.ts

@@ -10,9 +10,11 @@ import {
   getIssue,
   getIssueByShortId,
   getIssueInOrg,
+  type IssueSort,
+  listIssuesPaginated,
   triggerRootCauseAnalysis,
 } from "../../lib/api-client.js";
-import { parseIssueArg } from "../../lib/arg-parsing.js";
+import { type IssueSelector, parseIssueArg } from "../../lib/arg-parsing.js";
 import { getProjectByAlias } from "../../lib/db/project-aliases.js";
 import { detectAllDsns } from "../../lib/dsn/index.js";
 import { ApiError, ContextError, ResolutionError } from "../../lib/errors.js";
@@ -33,7 +35,7 @@ export const issueIdPositional = {
     {
       placeholder: "issue",
       brief:
-        "Issue: <org>/ID, <project>-suffix, ID, or suffix (e.g., sentry/CLI-G, cli-G, CLI-G, G)",
+        "Issue: @latest, @most_frequent, <org>/ID, <project>-suffix, ID, or suffix",
       parse: String,
     },
   ],
@@ -51,6 +53,10 @@ export const issueIdPositional = {
  * @param issueId - The user-provided issue ID
  */
 export function buildCommandHint(command: string, issueId: string): string {
+  // Selectors already include the @ prefix and are self-contained
+  if (issueId.startsWith("@")) {
+    return `sentry issue ${command} <org>/${issueId}`;
+  }
   // Numeric IDs always need org context - can't be combined with project
   if (isAllDigits(issueId)) {
     return `sentry issue ${command} <org>/${issueId}`;
@@ -231,6 +237,83 @@ function resolveExplicitOrgSuffix(
   );
 }
 
+/**
+ * Map magic selectors to Sentry issue list sort parameters.
+ *
+ * `@latest` → `"date"` (most recent `lastSeen` timestamp)
+ * `@most_frequent` → `"freq"` (highest event frequency)
+ */
+const SELECTOR_SORT_MAP: Record<IssueSelector, IssueSort> = {
+  "@latest": "date",
+  "@most_frequent": "freq",
+};
+
+/**
+ * Human-readable labels for selectors (used in error messages).
+ */
+const SELECTOR_LABELS: Record<IssueSelector, string> = {
+  "@latest": "most recent",
+  "@most_frequent": "most frequent",
+};
+
+/**
+ * Resolve a magic `@` selector to the top matching issue.
+ *
+ * Fetches the issue list sorted by the selector's criteria and returns
+ * the first result. Requires organization context (explicit or auto-detected).
+ *
+ * @param selector - The magic selector (e.g., `@latest`, `@most_frequent`)
+ * @param explicitOrg - Optional explicit org slug from `org/@selector` format
+ * @param cwd - Current working directory for context resolution
+ * @param commandHint - Hint for error messages
+ * @returns The resolved issue with org context
+ * @throws {ContextError} When organization cannot be resolved
+ * @throws {ResolutionError} When no issues match the selector
+ */
+async function resolveSelector(
+  selector: IssueSelector,
+  explicitOrg: string | undefined,
+  cwd: string,
+  commandHint: string
+): Promise<StrictResolvedIssue> {
+  // Resolve org: explicit from `org/@latest` or auto-detected from DSN/defaults
+  let orgSlug: string;
+  if (explicitOrg) {
+    orgSlug = await resolveEffectiveOrg(explicitOrg);
+  } else {
+    const resolved = await resolveOrg({ cwd });
+    if (!resolved) {
+      throw new ContextError("Organization", commandHint);
+    }
+    orgSlug = resolved.org;
+  }
+
+  const sort = SELECTOR_SORT_MAP[selector];
+  const label = SELECTOR_LABELS[selector];
+
+  // Fetch just the top issue with the appropriate sort
+  const { data: issues } = await listIssuesPaginated(orgSlug, "", {
+    sort,
+    perPage: 1,
+    query: "is:unresolved",
+  });
+
+  const issue = issues[0];
+  if (!issue) {
+    throw new ResolutionError(
+      `Selector '${selector}'`,
+      "no unresolved issues found",
+      commandHint,
+      [
+        `No unresolved issues found in org '${orgSlug}'.`,
+        `The ${label} issue selector only matches unresolved issues.`,
+      ]
+    );
+  }
+
+  return { org: orgSlug, issue };
+}
+
 /**
  * Options for resolving an issue ID.
  */
@@ -304,6 +387,7 @@ async function resolveNumericIssue(
  * Resolve an issue ID to organization slug and full issue object.
  *
  * Supports all issue ID formats (now parsed by parseIssueArg in arg-parsing.ts):
+ * - selector: "@latest", "sentry/@most_frequent" → top issue by criteria
  * - explicit: "sentry/cli-G" → org + project + suffix
  * - explicit-org-suffix: "sentry/G" → org + suffix (needs DSN for project)
  * - explicit-org-numeric: "sentry/123456789" → org + numeric ID
@@ -376,6 +460,10 @@ export async function resolveIssue(
       // Just suffix - need DSN for org and project
       return resolveSuffixOnly(parsed.suffix, cwd, commandHint);
 
+    case "selector":
+      // Magic @ selector - fetch top issue by sort criteria
+      return resolveSelector(parsed.selector, parsed.org, cwd, commandHint);
+
     default: {
       // Exhaustive check - this should never be reached
       const _exhaustive: never = parsed;

src/commands/issue/view.ts

@@ -84,11 +84,14 @@ export const viewCommand = buildCommand({
       "View detailed information about a Sentry issue by its ID or short ID. " +
       "The latest event is automatically included for full context.\n\n" +
       "Issue formats:\n" +
-      "  <org>/ID       - Explicit org: sentry/EXTENSION-7, sentry/cli-G\n" +
+      "  @latest         - Most recent unresolved issue\n" +
+      "  @most_frequent  - Issue with highest event frequency\n" +
+      "  <org>/ID        - Explicit org: sentry/EXTENSION-7, sentry/cli-G\n" +
+      "  <org>/@selector - Selector with org: my-org/@latest\n" +
       "  <project>-suffix - Project + suffix: cli-G, spotlight-electron-4Y\n" +
-      "  ID             - Short ID: CLI-G (searches across orgs)\n" +
-      "  suffix         - Suffix only: G (requires DSN context)\n" +
-      "  numeric        - Numeric ID: 123456789\n\n" +
+      "  ID              - Short ID: CLI-G (searches across orgs)\n" +
+      "  suffix          - Suffix only: G (requires DSN context)\n" +
+      "  numeric         - Numeric ID: 123456789\n\n" +
       "In multi-project mode (after 'issue list'), use alias-suffix format (e.g., 'f-g' " +
       "where 'f' is the project alias shown in the list).",
   },