fix(errors): surface user search-query 400s as ValidationError, keep CLI-built 400s reported (#1154)

## Why

Follow-up to #1151 based on review feedback: **silencing every
search-query 400 papers over a real bug class.**

HTTP 400 means the server rejected our request as malformed. That has
two distinct causes, only distinguishable at the command boundary (where
`flags.query` is in scope):

1. **The user typed an invalid `--query`** → a user input mistake.
2. **The CLI built an invalid query itself** (no user `--query`) → a
genuine CLI defect.

PR #1151 special-cased `isSearchQueryParseError()` in all three
classifiers (`classifySilenced`, `isUserError`, `isUserApiError`), which
silenced **both** — so CLI-authored bad queries became invisible.

## What changed

- **New `toSearchQueryError(error, userQuery, extraSuggestions?)`** in
`src/lib/errors.ts`: converts a parse-400 into a clean, actionable
`ValidationError` **only when the user supplied `--query`**. When
there's no user `--query`, the original `ApiError(400)` is returned
untouched so it stays reported to Sentry as the CLI bug it is.
- Wired in at the three command boundaries that accept `--query`: `issue
list` (both the single- and multi-project 400 paths), `explore`, and
`trace list`.
- **Removed** the `isSearchQueryParseError` special-case from
`classifySilenced` (+ dropped the `api_query_error` `SilenceReason`),
`isUserError`, and `isUserApiError`. A raw `ApiError(400)` is now always
treated as a reported CLI bug.

## Result

- User query typos → clean `ValidationError` with the server detail +
search-syntax help (correct exit code, no "CLI bug" upgrade nudge).
- CLI-constructed bad queries → still reported, so we can actually find
and fix them.

## Note

A user-query `ValidationError` is still surfaced to the user and (like
other `ValidationError`s) reaches Sentry — that volume is now a useful
signal for client-side query-linting UX rather than noise mislabeled as
a 400 crash. Happy to silence query `ValidationError`s separately if
preferred.

## Tests

- `toSearchQueryError` unit tests (convert vs passthrough, suggestions,
non-ApiError).
- `issue list` integration tests: user `--query` → `ValidationError`; no
`--query` → reported `ApiError(400)`.
- Updated `classifySilenced` / `isUserError` / `isUserApiError` tests to
assert search-query 400s are no longer silenced.
- Full unit suite for touched files green; lint + typecheck clean.

Author: BYK

.lore.md

@@ -15,7 +15,7 @@ import {
   hasPreviousPage,
   resolveCursor,
 } from "../../lib/db/pagination.js";
-import { ContextError } from "../../lib/errors.js";
+import { ContextError, toSearchQueryError } from "../../lib/errors.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { buildListCommand, paginationHint } from "../../lib/list-command.js";
 import { withProgress } from "../../lib/polling.js";
@@ -155,6 +155,9 @@ export const listCommand = buildListCommand("event", {
           full: flags.full,
           cursor,
           ...timeRangeToApiParams(timeRange),
+        }).catch((error: unknown): never => {
+          // An unparseable user --query is a user input mistake, not a CLI bug.
+          throw toSearchQueryError(error, flags.query);
         })
     );
 

src/commands/event/list.ts

@@ -20,7 +20,7 @@ import {
   hasPreviousPage,
   resolveCursor,
 } from "../lib/db/pagination.js";
-import { ValidationError } from "../lib/errors.js";
+import { toSearchQueryError, ValidationError } from "../lib/errors.js";
 import { filterFields } from "../lib/formatters/json.js";
 import { buildMetaColumns } from "../lib/formatters/meta-table.js";
 import { CommandOutput } from "../lib/formatters/output.js";
@@ -792,7 +792,13 @@ export const exploreCommand = buildListCommand("explore", {
         message: `Querying ${dataset} in ${project ? `${org}/${project}` : org}...`,
         json: flags.json,
       },
-      () => config.fetch({ cursor, limit: flags.limit, timeRange })
+      () =>
+        config
+          .fetch({ cursor, limit: flags.limit, timeRange })
+          .catch((error: unknown): never => {
+            // An unparseable user --query is a user input mistake, not a CLI bug.
+            throw toSearchQueryError(error, flags.query);
+          })
     );
 
     advancePaginationState(PAGINATION_KEY, contextKey, direction, nextCursor);

src/commands/explore.ts

@@ -12,7 +12,7 @@ import {
   hasPreviousPage,
   resolveCursor,
 } from "../../lib/db/pagination.js";
-import { ContextError } from "../../lib/errors.js";
+import { ContextError, toSearchQueryError } from "../../lib/errors.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { buildListCommand, paginationHint } from "../../lib/list-command.js";
 import { withProgress } from "../../lib/polling.js";
@@ -137,6 +137,9 @@ export const eventsCommand = buildListCommand("issue", {
           full: flags.full,
           cursor,
           ...timeRangeToApiParams(timeRange),
+        }).catch((error: unknown): never => {
+          // An unparseable user --query is a user input mistake, not a CLI bug.
+          throw toSearchQueryError(error, flags.query);
         })
     );
 

src/commands/issue/events.ts

@@ -40,6 +40,7 @@ import { createDsnFingerprint } from "../../lib/dsn/index.js";
 import {
   ApiError,
   ContextError,
+  toSearchQueryError,
   ValidationError,
   withAuthGuard,
 } from "../../lib/errors.js";
@@ -906,6 +907,13 @@ function enrichIssueListError(
   error: unknown,
   flags: Pick<ListFlags, "query" | "period" | "sort">
 ): never {
+  // A user-supplied --query the server cannot parse is a user input mistake,
+  // not a CLI bug: surface it as a ValidationError. A 400 with no user --query
+  // (the CLI built a bad query) falls through and stays a reported ApiError.
+  const queryError = toSearchQueryError(error, flags.query);
+  if (queryError !== error) {
+    throw queryError;
+  }
   if (error instanceof ApiError) {
     if (error.status === 400) {
       throw new ApiError(
@@ -1124,6 +1132,14 @@ async function handleResolvedTargets(
     const { error: first } = failures[0]!;
     const prefix = `Failed to fetch issues from ${targets.length} project(s)`;
 
+    // A user-supplied --query the server cannot parse is a user input mistake,
+    // not a CLI bug — surface it as a ValidationError before wrapping as a
+    // multi-project ApiError. CLI-authored 400s fall through and stay reported.
+    const queryError = toSearchQueryError(first, flags.query);
+    if (queryError !== first) {
+      throw queryError;
+    }
+
     // Propagate ApiError so telemetry sees the original status code.
     // For 400 errors, append actionable suggestions since the user's query
     // or parameters are likely malformed. Common causes: invalid Sentry

src/commands/issue/list.ts

@@ -22,6 +22,7 @@ import {
 import {
   AuthError,
   stringifyUnknown,
+  toSearchQueryError,
   ValidationError,
 } from "../../lib/errors.js";
 import {
@@ -180,6 +181,9 @@ async function executeSingleFetch(
     ...timeRangeToApiParams(timeRange),
     sort: flags.sort,
     extraFields: flags.fields,
+  }).catch((error: unknown): never => {
+    // An unparseable user --query is a user input mistake, not a CLI bug.
+    throw toSearchQueryError(error, flags.query);
   });
 
   const periodLabel =
@@ -317,7 +321,8 @@ function renderLogRows(
  * Execute a single poll iteration in follow mode.
  *
  * Returns the new logs, or `undefined` if a transient error occurred
- * (reported via `onDiagnostic`). Re-throws {@link AuthError}.
+ * (reported via `onDiagnostic`). Re-throws {@link AuthError} and
+ * {@link ValidationError} (a converted bad-`--query` 400).
  */
 async function fetchPoll<T extends LogLike>(
   config: FollowGeneratorConfig<T>,
@@ -330,6 +335,12 @@ async function fetchPoll<T extends LogLike>(
     if (error instanceof AuthError) {
       throw error;
     }
+    // A ValidationError here is a converted search-query 400 (bad user
+    // --query). It is a user input mistake, not a transient fetch failure, so
+    // surface it and stop the stream rather than capturing it as a CLI bug.
+    if (error instanceof ValidationError) {
+      throw error;
+    }
     Sentry.captureException(error);
     const message = stringifyUnknown(error);
     config.onDiagnostic(`Error fetching logs: ${message}\n`);
@@ -485,6 +496,9 @@ async function executeTraceSingleFetch(
     limit: flags.limit,
     ...timeRangeToApiParams(timeRange),
     sort: flags.sort,
+  }).catch((error: unknown): never => {
+    // An unparseable user --query is a user input mistake, not a CLI bug.
+    throw toSearchQueryError(error, flags.query);
   });
 
   const periodLabel =
@@ -825,6 +839,10 @@ export const listCommand = buildListCommand(
                 query: traceQuery,
                 limit: flags.limit,
                 statsPeriod,
+              }).catch((error: unknown): never => {
+                // An unparseable user --query is a user input mistake, not a
+                // CLI bug — surface it as an actionable ValidationError.
+                throw toSearchQueryError(error, flags.query);
               }),
             extractNew: (logs, lastTs) =>
               logs.filter((l) => {
@@ -896,6 +914,10 @@ export const listCommand = buildListCommand(
                 statsPeriod,
                 afterTimestamp,
                 extraFields: flags.fields,
+              }).catch((error: unknown): never => {
+                // An unparseable user --query is a user input mistake, not a
+                // CLI bug — surface it as an actionable ValidationError.
+                throw toSearchQueryError(error, flags.query);
               }),
             extractNew: (logs) => logs,
           });

src/commands/log/list.ts

@@ -17,6 +17,7 @@ import {
   hasPreviousPage,
   resolveCursor,
 } from "../../lib/db/pagination.js";
+import { toSearchQueryError } from "../../lib/errors.js";
 import {
   escapeMarkdownCell,
   formatRelativeTime,
@@ -364,6 +365,9 @@ export const listCommand = buildListCommand("replay", {
           sort: flags.sort,
           cursor,
           ...timeRangeToApiParams(timeRange),
+        }).catch((error: unknown): never => {
+          // An unparseable user --query is a user input mistake, not a CLI bug.
+          throw toSearchQueryError(error, flags.query);
         })
     );
 

src/commands/replay/list.ts

@@ -20,6 +20,7 @@ import {
   hasPreviousPage,
   resolveCursor,
 } from "../../lib/db/pagination.js";
+import { toSearchQueryError } from "../../lib/errors.js";
 import {
   type FlatSpan,
   formatSpanTable,
@@ -390,6 +391,9 @@ async function handleTraceMode(
         ...timeRangeToApiParams(timeRange),
         extraFields: extraApiFields,
         allProjects: true,
+      }).catch((error: unknown): never => {
+        // An unparseable user --query is a user input mistake, not a CLI bug.
+        throw toSearchQueryError(error, flags.query);
       })
   );
 
@@ -471,6 +475,9 @@ async function handleProjectMode(
         cursor,
         ...timeRangeToApiParams(timeRange),
         extraFields: extraApiFields,
+      }).catch((error: unknown): never => {
+        // An unparseable user --query is a user input mistake, not a CLI bug.
+        throw toSearchQueryError(error, flags.query);
       })
   );
 

src/commands/span/list.ts

@@ -13,6 +13,7 @@ import {
   hasPreviousPage,
   resolveCursor,
 } from "../../lib/db/pagination.js";
+import { toSearchQueryError } from "../../lib/errors.js";
 import { formatTraceTable } from "../../lib/formatters/index.js";
 import { filterFields } from "../../lib/formatters/json.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
@@ -289,6 +290,9 @@ export const listCommand = buildListCommand("trace", {
           sort: flags.sort,
           cursor,
           ...timeRangeToApiParams(timeRange),
+        }).catch((error: unknown): never => {
+          // An unparseable user --query is a user input mistake, not a CLI bug.
+          throw toSearchQueryError(error, flags.query);
         })
     );
 

src/commands/trace/list.ts

@@ -13,6 +13,7 @@ import {
 } from "../../lib/arg-parsing.js";
 import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
+import { toSearchQueryError } from "../../lib/errors.js";
 import { filterFields } from "../../lib/formatters/json.js";
 import { formatLogTable } from "../../lib/formatters/log.js";
 import { CommandOutput, formatFooter } from "../../lib/formatters/output.js";
@@ -207,6 +208,9 @@ export const logsCommand = buildCommand({
           limit: flags.limit,
           query,
           sort: flags.sort,
+        }).catch((error: unknown): never => {
+          // An unparseable user --query is a user input mistake, not a CLI bug.
+          throw toSearchQueryError(error, flags.query);
         })
     );