feat(local): address remaining important gaps

- Deduplicate parsePort: export from server.ts, import in run.ts
- Fix signal handler leak in run.ts: store refs, remove in finally,
  add settled flag to prevent close/error race
- Add SSE reconnection with exponential backoff and Last-Event-ID
  resume support in the SSE consumer
- Add --format json flag for NDJSON output (machine-readable output
  for AI coding agents and automation tools)
- Preserve existing SENTRY_TRACES_SAMPLE_RATE (use ?? fallback)
- Add agent monitoring section to docs with gen_ai/mcp examples
- Add JSON output section to docs
- Add server.test.ts: parsePort, feedSSELine (with id tracking),
  buildApp (health, ingest, CORS, SSE, 413 rejection), isServerRunning
- Expand run.test.ts: -- separator stripping, ENOENT handling,
  SENTRY_TRACES_SAMPLE_RATE preservation

Author: BYK

docs/src/fragments/commands/local.md

@@ -64,3 +64,32 @@ sentry local -f error -f log    # only errors and logs
 ```
 
 Use `--quiet` to suppress tail output entirely if you only need the SSE stream.
+
+## Agent monitoring
+
+`sentry local` shows rich output for AI agent spans when your SDK instruments with [OpenTelemetry semantic attributes](https://opentelemetry.io/docs/specs/semconv/gen-ai/):
+
+```
+14:32:01 [TRACE]   [SERVER]  [gen_ai] chat anthropic/claude-4-sonnet [1200ms] [5 spans]
+14:32:02 [TRACE]   [SERVER]  [mcp] tools/call search_files [320ms]
+14:32:03 [TRACE]   [SERVER]  [db] SELECT users [postgresql] [12ms]
+14:32:04 [ERROR]   [SERVER]  RateLimitError: API quota exceeded [api_client.py:42]
+```
+
+GenAI operations show the model name, MCP tool calls show the tool being invoked, and database queries show the system and query summary. This works automatically when your Sentry SDK is configured with AI/LLM integrations.
+
+## JSON output
+
+Use `--format json` (or `-F json`) for machine-readable NDJSON output, one JSON object per envelope item:
+
+```bash
+sentry local --format json
+```
+
+```json
+{"type":"transaction","timestamp":1700000001,"op":"gen_ai","label":"chat anthropic/claude-4-sonnet","duration_ms":1200,"span_count":5,"source":"server"}
+{"type":"error","timestamp":1700000002,"error_type":"RateLimitError","message":"API quota exceeded","source":"server"}
+{"type":"log","timestamp":1700000003,"level":"info","message":"User logged in","attributes":{"user_id":1234},"source":"server"}
+```
+
+This is useful for AI coding agents and automation tools that need to consume Sentry events programmatically.

src/commands/local/run.ts

@@ -21,6 +21,7 @@ import {
   buildApp,
   DEFAULT_PORT,
   isServerRunning,
+  parsePort,
   tryListen,
 } from "./server.js";
 
@@ -29,18 +30,6 @@ type RunFlags = {
   readonly host: string;
 };
 
-/** Parse and validate a port number. */
-function parsePort(value: string): number {
-  const port = Number(value);
-  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
-    throw new ValidationError(
-      `Invalid port: ${value}. Must be an integer between 0 and 65535.`,
-      "port"
-    );
-  }
-  return port;
-}
-
 /** Buffer size for the auto-started background server. */
 const BUFFER_SIZE = 500;
 
@@ -140,7 +129,8 @@ export const runCommand = buildCommand({
           ...process.env,
           SENTRY_SPOTLIGHT: spotlightUrl,
           NEXT_PUBLIC_SENTRY_SPOTLIGHT: spotlightUrl,
-          SENTRY_TRACES_SAMPLE_RATE: "1",
+          SENTRY_TRACES_SAMPLE_RATE:
+            process.env.SENTRY_TRACES_SAMPLE_RATE ?? "1",
         },
         stdio: "inherit",
       });
@@ -155,23 +145,34 @@ export const runCommand = buildCommand({
     }
 
     // Forward signals to the child so the whole process tree shuts down.
-    const forwardSignal = (signal: NodeJS.Signals) => {
-      child.kill(signal);
-    };
-    process.once("SIGINT", () => forwardSignal("SIGINT"));
-    process.once("SIGTERM", () => forwardSignal("SIGTERM"));
+    // Store references so handlers can be removed in finally.
+    const onSigint = () => child.kill("SIGINT");
+    const onSigterm = () => child.kill("SIGTERM");
+    process.once("SIGINT", onSigint);
+    process.once("SIGTERM", onSigterm);
 
     let exitCode: number;
     try {
       exitCode = await new Promise<number>((resolve, reject) => {
-        child.on("close", (code) => resolve(code ?? 1));
+        let settled = false;
+        child.on("close", (code) => {
+          if (!settled) {
+            settled = true;
+            resolve(code ?? 1);
+          }
+        });
         // If spawn itself fails (e.g. ENOENT), 'close' may never fire.
         child.on("error", (err) => {
           logger.debug(`Child process error: ${err.message}`);
-          reject(err);
+          if (!settled) {
+            settled = true;
+            reject(err);
+          }
         });
       });
     } finally {
+      process.removeListener("SIGINT", onSigint);
+      process.removeListener("SIGTERM", onSigterm);
       if (bgServer) {
         logger.info("Stopping background server...");
         await shutdownServer(bgServer);