oauth: let the debugger's warnings arrive as warnings

mcpjam-inspector/client/src/lib/__tests__/error-reporting.test.ts

@@ -147,6 +147,31 @@ describe("reportCaught", () => {
     );
   });
 
+  // Sentry reads `level`; PostHog error tracking reads `$exception_level`, and
+  // groups, alerts and filters on it. Sending only `level` left every report at
+  // PostHog's `error` default, which silently overrode the one caller that asks
+  // for something quieter.
+  it("declares the level on the key PostHog actually reads", () => {
+    reportCaught(new Error("server under test misbehaved"), {
+      source: "oauth_debugger_step",
+      level: "warning",
+    });
+
+    expect(posthogCaptureException).toHaveBeenCalledWith(
+      expect.any(Error),
+      expect.objectContaining({ $exception_level: "warning" }),
+    );
+  });
+
+  it("still defaults to error when the caller names no level", () => {
+    reportCaught(new Error("boom"), { source: "unit" });
+
+    expect(posthogCaptureException).toHaveBeenCalledWith(
+      expect.any(Error),
+      expect.objectContaining({ $exception_level: "error" }),
+    );
+  });
+
   it("reports to Sentry but NOT PostHog on a non-capture surface", async () => {
     // `capture_exceptions: false` only disables posthog-js's automatic
     // window.onerror handler — an explicit captureException still sends. A

mcpjam-inspector/client/src/lib/error-reporting.ts

@@ -189,6 +189,22 @@ export function reportCaught(error: unknown, options: ReportOptions): void {
       posthog.captureException(normalized, {
         source: options.source,
         level: options.level ?? "error",
+        // The severity PostHog actually reads. `captureException(err, props)`
+        // merges `props` OVER the properties it built, and error tracking
+        // groups, alerts and filters on `$exception_level` — so the plain
+        // `level` above lands as a custom property nothing looks at, and every
+        // report kept the `error` default no matter what the caller declared.
+        //
+        // That silently overrode the one caller that asks for anything else.
+        // `oauth_debugger_step` is `warning` on purpose — it reports the
+        // server UNDER TEST misbehaving, which is what a debugger is for, and
+        // its value is the aggregate trend rather than a page. It alerted as
+        // an Inspector crash anyway: 378 events across 97 users in 18 days,
+        // more than half of every client `$exception` in the project.
+        //
+        // `level` is kept alongside it: it has been on these events since the
+        // sink was written, and dropping it would break any saved filter.
+        $exception_level: options.level ?? "error",
         ...(options.extra ?? {}),
       });
     }

mcpjam-inspector/client/src/lib/oauth/__tests__/debug-state-machine-step-reporting.test.ts

@@ -163,6 +163,43 @@ describe("OAuth debugger step-failure reporting", () => {
     expect(reportCaught).toHaveBeenCalledTimes(2);
   });
 
+  it("reports one failure once when the hint is appended after it", () => {
+    // The SDK writes the bare message, then the same message with the recovery
+    // hint (`errorWithFallbackHint`). Two strings, one refusal — and exact
+    // comparison reported both, a millisecond apart.
+    const { wrapped } = wrappedUpdateState();
+
+    wrapped({ error: "Dynamic Client Registration failed (400)." });
+    wrapped({
+      error:
+        "Dynamic Client Registration failed (400). Configure a pre-registered client or enable DCR on the authorization server.",
+    });
+
+    expect(reportCaught).toHaveBeenCalledTimes(1);
+  });
+
+  it("swallows the pair in the other order too", () => {
+    // Nothing guarantees which of the two lands first, and a guard that only
+    // works one way round is a guard that works half the time.
+    const { wrapped } = wrappedUpdateState();
+
+    wrapped({ error: "Client registration failed: timeout. Configure a pre-registered client." });
+    wrapped({ error: "Client registration failed: timeout." });
+
+    expect(reportCaught).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not swallow a different failure that merely follows", () => {
+    // The narrowness is the point: an unrelated message never begins with the
+    // whole text of the one before it.
+    const { wrapped } = wrappedUpdateState();
+
+    wrapped({ error: "Dynamic Client Registration failed (400)." });
+    wrapped({ error: "Authenticated request failed: 401 Unauthorized" });
+
+    expect(reportCaught).toHaveBeenCalledTimes(2);
+  });
+
   it("still forwards every update to the caller's updateState", () => {
     const { wrapped, updateState } = wrappedUpdateState();
 

mcpjam-inspector/client/src/lib/oauth/debug-state-machine-adapter.ts

@@ -272,6 +272,28 @@ const UNREPORTED_STEP_FAILURES = new Set([
   AUTHORIZATION_SERVER_METADATA_MISSING_ISSUER,
 ]);
 
+/**
+ * One failure, or two?
+ *
+ * A step that fails twice over — DCR, say — writes its bare message first and
+ * then the same message with the recovery hint appended
+ * (`errorWithFallbackHint` in the SDK is `${error} ${FALLBACK_HINT}`). Exact
+ * comparison saw two different strings and reported both, one millisecond
+ * apart, so a single refusal arrived as a pair: 29 of 378 events over 18 days.
+ *
+ * Prefix, not equality, and in whichever order they arrive. This is
+ * deliberately narrow — an unrelated failure never begins with the whole text
+ * of the one before it, so widening a step's message cannot swallow the next
+ * step's.
+ */
+function isSameStepFailure(
+  error: string,
+  lastReported: string | undefined
+): boolean {
+  if (lastReported === undefined) return false;
+  return error.startsWith(lastReported) || lastReported.startsWith(error);
+}
+
 /**
  * Wrap the caller's `updateState` so every NEW step failure is reported.
  *
@@ -309,7 +331,11 @@ function withStepFailureReporting(
       updateState(updates);
       return;
     }
-    if (typeof error === "string" && error !== "" && error !== lastReportedError) {
+    if (
+      typeof error === "string" &&
+      error !== "" &&
+      !isSameStepFailure(error, lastReportedError)
+    ) {
       lastReportedError = error;
       reportCaught(new Error(sanitizeStepError(error)), {
         source: "oauth_debugger_step",