@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/src/tests/mcp-oauth-wrapper.test.ts

@@ -1,14 +1,17 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import {
   assertUrlSafe,
+  authMethodForStoredClient,
   buildAuthorizeUrl,
   computeExpiresAt,
   discoverAuthorizationServerMetadata,
   discoverProtectedResourceMetadata,
   exchangeCodeForTokens,
+  normalizeTokenEndpointAuthMethod,
   refreshMcpToken,
   registerClient,
   revokeMcpToken,
+  selectDcrTokenEndpointAuthMethod,
 } from "../oauth/mcp-wrapper";
 
 // ─── SSRF guard ──────────────────────────────────────────────────────────────
@@ -417,6 +420,26 @@ describe("registerClient (RFC 7591 DCR)", () => {
       }),
     ).rejects.toThrow(/Dynamic client registration failed/);
   });
+
+  test("attaches a bounded AbortSignal so a non-responding registration endpoint can't hang the caller forever", async () => {
+    let capturedSignal: AbortSignal | null | undefined;
+    globalThis.fetch = async (_url: string | URL | Request, init?: RequestInit) => {
+      capturedSignal = init?.signal;
+      return new Response(JSON.stringify({ client_id: "x" }), { status: 201 });
+    };
+
+    await registerClient("https://as.example.com/register", {
+      client_name: "x",
+      redirect_uris: ["https://swarm.example.com/cb"],
+    });
+
+    // Every safeFetch call (metadata discovery, DCR, token exchange,
+    // refresh, revocation) gets a default timeout — without it, a provider
+    // that accepts the connection and never responds would hold the
+    // per-connector authorize-flow lock indefinitely.
+    expect(capturedSignal).toBeInstanceOf(AbortSignal);
+    expect(capturedSignal?.aborted).toBe(false);
+  });
 });
 
 // ─── Token exchange + refresh + revoke ───────────────────────────────────────
@@ -449,6 +472,7 @@ describe("exchangeCodeForTokens", () => {
       tokenUrl: "https://as.example.com/token",
       clientId: "client-xyz",
       clientSecret: "secret-xyz",
+      tokenEndpointAuthMethod: "client_secret_post",
       redirectUri: "https://swarm.example.com/callback",
       code: "authcode-1",
       codeVerifier: "verifier-1",
@@ -525,6 +549,38 @@ describe("refreshMcpToken", () => {
       }),
     ).rejects.toThrow(/Token refresh failed \(400\)/);
   });
+
+  test("scrubs an echoed client_secret/refresh_token from the thrown error body", async () => {
+    const clientSecret = "super-secret-client-value-123456";
+    const refreshToken = "super-secret-refresh-value-654321";
+    globalThis.fetch = async () =>
+      new Response(
+        JSON.stringify({
+          error: "invalid_client",
+          error_description: `client_secret ${clientSecret} rejected for refresh_token ${refreshToken}`,
+        }),
+        { status: 401 },
+      );
+
+    let thrown: Error | undefined;
+    try {
+      await refreshMcpToken({
+        tokenUrl: "https://as.example.com/token",
+        clientId: "c",
+        clientSecret,
+        refreshToken,
+        resource: "https://mcp.example.com/",
+      });
+    } catch (err) {
+      thrown = err as Error;
+    }
+
+    expect(thrown).toBeDefined();
+    expect(thrown!.message).not.toContain(clientSecret);
+    expect(thrown!.message).not.toContain(refreshToken);
+    expect(thrown!.message).toMatch(/\[REDACTED:mcp_oauth_client_secret]/);
+    expect(thrown!.message).toMatch(/\[REDACTED:mcp_oauth_refresh_token]/);
+  });
 });
 
 describe("revokeMcpToken (RFC 7009)", () => {
@@ -545,6 +601,7 @@ describe("revokeMcpToken (RFC 7009)", () => {
       token: "t-1",
       clientId: "c",
       tokenTypeHint: "refresh_token",
+      tokenEndpointAuthMethod: "client_secret_post",
     });
 
     const params = new URLSearchParams(capturedBody ?? "");
@@ -565,6 +622,381 @@ describe("revokeMcpToken (RFC 7009)", () => {
   });
 });
 
+// ─── Token endpoint client authentication (RFC 6749 §2.3.1 / RFC 7591 §2) ────
+
+describe("selectDcrTokenEndpointAuthMethod", () => {
+  test("prefers client_secret_basic when the AS advertises it", () => {
+    expect(
+      selectDcrTokenEndpointAuthMethod(["client_secret_post", "client_secret_basic", "none"]),
+    ).toBe("client_secret_basic");
+  });
+
+  test("falls back to client_secret_post when basic isn't advertised", () => {
+    expect(selectDcrTokenEndpointAuthMethod(["client_secret_post", "none"])).toBe(
+      "client_secret_post",
+    );
+  });
+
+  test("falls back to none when only public-client auth is advertised", () => {
+    expect(selectDcrTokenEndpointAuthMethod(["none"])).toBe("none");
+  });
+
+  test("an explicitly empty advertised list takes the RFC 8414 default, it is not an incompatibility", () => {
+    // Degenerate serialization, not a claim to support nothing. Erroring here
+    // would break such a provider outright for no safety gain.
+    expect(selectDcrTokenEndpointAuthMethod([])).toBe("client_secret_basic");
+  });
+
+  test("throws when the AS advertises only methods we cannot perform", () => {
+    // Silently registering a Basic client against an AS that offers only
+    // private_key_jwt produces a client we can never authenticate, surfacing
+    // later as an opaque invalid_client. Fail early and actionably instead.
+    expect(() => selectDcrTokenEndpointAuthMethod(["private_key_jwt"])).toThrow(/cannot perform/);
+  });
+
+  test("defaults to client_secret_basic when metadata is absent (RFC 7591 §2)", () => {
+    expect(selectDcrTokenEndpointAuthMethod(undefined)).toBe("client_secret_basic");
+    expect(selectDcrTokenEndpointAuthMethod([])).toBe("client_secret_basic");
+  });
+});
+
+describe("normalizeTokenEndpointAuthMethod", () => {
+  test("passes through known values", () => {
+    expect(normalizeTokenEndpointAuthMethod("client_secret_basic")).toBe("client_secret_basic");
+    expect(normalizeTokenEndpointAuthMethod("client_secret_post")).toBe("client_secret_post");
+    expect(normalizeTokenEndpointAuthMethod("none")).toBe("none");
+  });
+
+  test("defaults missing/unknown values to client_secret_basic, not body-post", () => {
+    expect(normalizeTokenEndpointAuthMethod(undefined)).toBe("client_secret_basic");
+    expect(normalizeTokenEndpointAuthMethod(null)).toBe("client_secret_basic");
+    expect(normalizeTokenEndpointAuthMethod("")).toBe("client_secret_basic");
+    expect(normalizeTokenEndpointAuthMethod("private_key_jwt")).toBe("client_secret_basic");
+  });
+});
+
+describe("authMethodForStoredClient", () => {
+  test("preserves legacy body-post behavior when the field is absent", () => {
+    expect(authMethodForStoredClient(undefined)).toBe("client_secret_post");
+    expect(authMethodForStoredClient(null)).toBe("client_secret_post");
+    expect(authMethodForStoredClient("")).toBe("client_secret_post");
+  });
+});
+
+describe("token-endpoint client authentication is applied per the registered method", () => {
+  const original = globalThis.fetch;
+  afterEach(() => {
+    globalThis.fetch = original;
+  });
+
+  async function captureExchange(
+    tokenEndpointAuthMethod: string | null | undefined,
+    creds: { clientId?: string; clientSecret?: string } = {},
+  ) {
+    let capturedBody = "";
+    let capturedHeaders: Record<string, string> = {};
+    globalThis.fetch = async (_url: string | URL | Request, init?: RequestInit) => {
+      capturedBody = (init?.body as string) ?? "";
+      capturedHeaders = (init?.headers as Record<string, string>) ?? {};
+      return new Response(JSON.stringify({ access_token: "at-1" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    };
+    await exchangeCodeForTokens({
+      tokenUrl: "https://as.example.com/token",
+      clientId: creds.clientId ?? "client-xyz",
+      clientSecret: creds.clientSecret ?? "secret-xyz",
+      tokenEndpointAuthMethod,
+      redirectUri: "https://swarm.example.com/callback",
+      code: "authcode-1",
+      codeVerifier: "verifier-1",
+      resource: "https://mcp.example.com/",
+    });
+    return { params: new URLSearchParams(capturedBody), headers: capturedHeaders };
+  }
+
+  test("client_secret_basic → Authorization: Basic header, no creds in the body", async () => {
+    const { params, headers } = await captureExchange("client_secret_basic");
+    expect(headers.Authorization).toBe(
+      `Basic ${Buffer.from("client-xyz:secret-xyz").toString("base64")}`,
+    );
+    expect(params.get("client_id")).toBeNull();
+    expect(params.get("client_secret")).toBeNull();
+  });
+
+  test("client_secret_post → client_id/client_secret in the body, no Authorization header", async () => {
+    const { params, headers } = await captureExchange("client_secret_post");
+    expect(headers.Authorization).toBeUndefined();
+    expect(params.get("client_id")).toBe("client-xyz");
+    expect(params.get("client_secret")).toBe("secret-xyz");
+  });
+
+  test("none → client_id only in the body, no secret anywhere", async () => {
+    const { params, headers } = await captureExchange("none");
+    expect(headers.Authorization).toBeUndefined();
+    expect(params.get("client_id")).toBe("client-xyz");
+    expect(params.get("client_secret")).toBeNull();
+  });
+
+  test("Basic credentials are form-urlencoded per RFC 6749 §2.3.1, not encodeURIComponent", async () => {
+    // A space form-encodes to "+", not "%20", and !'()* must be escaped.
+    // Getting this wrong sends a different secret than the AS stored, which
+    // surfaces as an opaque invalid_client at exchange, refresh and revoke.
+    const clientId = "client id!";
+    const clientSecret = "se cret*(a)";
+    const { headers } = await captureExchange("client_secret_basic", { clientId, clientSecret });
+
+    const decoded = Buffer.from(
+      (headers.Authorization ?? "").replace(/^Basic /, ""),
+      "base64",
+    ).toString();
+    // `*` is intentionally literal: the urlencoded serializer preserves
+    // alphanumerics plus *-._ and encodes everything else.
+    expect(decoded).toBe("client+id%21:se+cret*%28a%29");
+    expect(decoded).not.toContain("%20");
+  });
+
+  test("a SHORT client secret is redacted even though registerVolatileSecret ignores it", async () => {
+    // registerVolatileSecret drops values under its minimum length, and RFC
+    // 7591 sets no floor on a client_secret, so redaction cannot rely on it.
+    const shortSecret = "s3cr3t";
+    globalThis.fetch = async () =>
+      new Response(`{"error":"invalid_client","detail":"bad secret ${shortSecret}"}`, {
+        status: 401,
+      });
+
+    await exchangeCodeForTokens({
+      tokenUrl: "https://as.example.com/token",
+      clientId: "client-xyz",
+      clientSecret: shortSecret,
+      tokenEndpointAuthMethod: "client_secret_post",
+      redirectUri: "https://swarm.example.com/callback",
+      code: "authcode-1",
+      codeVerifier: "verifier-1",
+      resource: "https://mcp.example.com/",
+    }).catch((err: Error) => {
+      expect(err.message).toContain("Token exchange failed (401)");
+      expect(err.message).not.toContain(shortSecret);
+    });
+  });
+
+  test("the code, verifier and encoded credential forms are redacted too", async () => {
+    const secret = "se cret with spaces";
+    const encodedSecret = new URLSearchParams({ v: secret }).toString().slice(2);
+    const code = "authcode-echoed";
+    const verifier = "verifier-echoed";
+    globalThis.fetch = async () =>
+      new Response(`{"detail":"${encodedSecret} ${code} ${verifier}"}`, { status: 400 });
+
+    await exchangeCodeForTokens({
+      tokenUrl: "https://as.example.com/token",
+      clientId: "client-xyz",
+      clientSecret: secret,
+      tokenEndpointAuthMethod: "client_secret_basic",
+      redirectUri: "https://swarm.example.com/callback",
+      code,
+      codeVerifier: verifier,
+      resource: "https://mcp.example.com/",
+    }).catch((err: Error) => {
+      expect(err.message).not.toContain(encodedSecret);
+      expect(err.message).not.toContain(code);
+      expect(err.message).not.toContain(verifier);
+      expect(err.message).not.toContain(secret);
+    });
+  });
+
+  test("form-encoded code and verifier are redacted when they contain reserved characters", async () => {
+    // A base64ish code like "a+b/c=" travels as "a%2Bb%2Fc%3D". Redacting only
+    // the raw value leaves the echoed body untouched. Earlier tests used
+    // URL-safe values, so they could not catch this.
+    const code = "a+b/c=";
+    const verifier = "v+e/r=";
+    const encode = (v: string) => new URLSearchParams({ v }).toString().slice(2);
+    globalThis.fetch = async () =>
+      new Response(`{"detail":"code=${encode(code)}&code_verifier=${encode(verifier)}"}`, {
+        status: 400,
+      });
+
+    await exchangeCodeForTokens({
+      tokenUrl: "https://as.example.com/token",
+      clientId: "client-xyz",
+      clientSecret: "secret-xyz",
+      tokenEndpointAuthMethod: "client_secret_post",
+      redirectUri: "https://swarm.example.com/callback",
+      code,
+      codeVerifier: verifier,
+      resource: "https://mcp.example.com/",
+    }).catch((err: Error) => {
+      expect(err.message).not.toContain(encode(code));
+      expect(err.message).not.toContain(encode(verifier));
+      expect(err.message).not.toContain(code);
+      expect(err.message).not.toContain(verifier);
+    });
+  });
+
+  test("a form-encoded refresh token is redacted on a failed refresh", async () => {
+    const refreshToken = "rt+slash/eq=";
+    const encoded = new URLSearchParams({ v: refreshToken }).toString().slice(2);
+    globalThis.fetch = async () =>
+      new Response(`{"detail":"refresh_token=${encoded}"}`, { status: 400 });
+
+    await refreshMcpToken({
+      tokenUrl: "https://as.example.com/token",
+      clientId: "client-xyz",
+      clientSecret: "secret-xyz",
+      tokenEndpointAuthMethod: "client_secret_post",
+      refreshToken,
+      resource: "https://mcp.example.com/",
+    }).catch((err: Error) => {
+      expect(err.message).toContain("Token refresh failed (400)");
+      expect(err.message).not.toContain(encoded);
+      expect(err.message).not.toContain(refreshToken);
+    });
+  });
+
+  test("a form-encoded revoked token is redacted on a failed revocation", async () => {
+    const token = "tok+slash/eq=";
+    const encoded = new URLSearchParams({ v: token }).toString().slice(2);
+    globalThis.fetch = async () => new Response(`{"detail":"token=${encoded}"}`, { status: 400 });
+
+    await revokeMcpToken({
+      revocationUrl: "https://as.example.com/revoke",
+      token,
+      clientId: "client-xyz",
+      clientSecret: "secret-xyz",
+      tokenEndpointAuthMethod: "client_secret_post",
+    }).catch((err: Error) => {
+      expect(err.message).toContain("Token revocation failed (400)");
+      expect(err.message).not.toContain(encoded);
+      expect(err.message).not.toContain(token);
+    });
+  });
+
+  test("an upstream error body echoing the client secret is scrubbed before it is thrown", async () => {
+    // The callback logs this message AND reflects it into the dashboard
+    // redirect as error_description, so an echoed credential would escape.
+    const secret = "sk-echoed-secret-value-1234567890";
+    globalThis.fetch = async () =>
+      new Response(`{"error":"invalid_client","detail":"bad client_secret: ${secret}"}`, {
+        status: 401,
+      });
+
+    await expect(
+      exchangeCodeForTokens({
+        tokenUrl: "https://as.example.com/token",
+        clientId: "client-xyz",
+        clientSecret: secret,
+        tokenEndpointAuthMethod: "client_secret_basic",
+        redirectUri: "https://swarm.example.com/callback",
+        code: "authcode-1",
+        codeVerifier: "verifier-1",
+        resource: "https://mcp.example.com/",
+      }),
+    ).rejects.toThrow(/Token exchange failed \(401\)/);
+
+    await exchangeCodeForTokens({
+      tokenUrl: "https://as.example.com/token",
+      clientId: "client-xyz",
+      clientSecret: secret,
+      tokenEndpointAuthMethod: "client_secret_basic",
+      redirectUri: "https://swarm.example.com/callback",
+      code: "authcode-1",
+      codeVerifier: "verifier-1",
+      resource: "https://mcp.example.com/",
+    }).catch((err: Error) => {
+      expect(err.message).not.toContain(secret);
+    });
+  });
+
+  test("a revocation error body echoing the token is scrubbed before it is thrown", async () => {
+    const token = "rt-echoed-refresh-token-0987654321";
+    globalThis.fetch = async () => new Response(`{"error":"bad token: ${token}"}`, { status: 400 });
+
+    await revokeMcpToken({
+      revocationUrl: "https://as.example.com/revoke",
+      token,
+      clientId: "client-xyz",
+      clientSecret: "secret-xyz",
+      tokenEndpointAuthMethod: "client_secret_post",
+    }).catch((err: Error) => {
+      expect(err.message).toContain("Token revocation failed (400)");
+      expect(err.message).not.toContain(token);
+    });
+  });
+
+  test("missing/unknown value defaults to client_secret_basic, never the old body-post behavior", async () => {
+    for (const missing of [undefined, null, "some-unknown-method"]) {
+      const { params, headers } = await captureExchange(missing);
+      expect(headers.Authorization).toBe(
+        `Basic ${Buffer.from("client-xyz:secret-xyz").toString("base64")}`,
+      );
+      expect(params.get("client_id")).toBeNull();
+      expect(params.get("client_secret")).toBeNull();
+    }
+  });
+
+  test("a public client recorded as basic identifies itself in the body", async () => {
+    let capturedBody = "";
+    let capturedHeaders: Record<string, string> = {};
+    globalThis.fetch = async (_url: string | URL | Request, init?: RequestInit) => {
+      capturedBody = (init?.body as string) ?? "";
+      capturedHeaders = (init?.headers as Record<string, string>) ?? {};
+      return new Response(JSON.stringify({ access_token: "at-1" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    };
+
+    await exchangeCodeForTokens({
+      tokenUrl: "https://as.example.com/token",
+      clientId: "public-client",
+      clientSecret: null,
+      tokenEndpointAuthMethod: "client_secret_basic",
+      redirectUri: "https://swarm.example.com/callback",
+      code: "authcode-1",
+      codeVerifier: "verifier-1",
+      resource: "https://mcp.example.com/",
+    });
+
+    const params = new URLSearchParams(capturedBody);
+    expect(capturedHeaders.Authorization).toBeUndefined();
+    expect(params.get("client_id")).toBe("public-client");
+    expect(params.get("client_secret")).toBeNull();
+  });
+
+  test("refreshMcpToken applies the same rule on the refresh_token grant", async () => {
+    let capturedHeaders: Record<string, string> = {};
+    let capturedBody = "";
+    globalThis.fetch = async (_url: string | URL | Request, init?: RequestInit) => {
+      capturedBody = (init?.body as string) ?? "";
+      capturedHeaders = (init?.headers as Record<string, string>) ?? {};
+      return new Response(JSON.stringify({ access_token: "new-at" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    };
+
+    await refreshMcpToken({
+      tokenUrl: "https://as.example.com/token",
+      clientId: "client-xyz",
+      clientSecret: "secret-xyz",
+      tokenEndpointAuthMethod: "client_secret_basic",
+      refreshToken: "rt-abc",
+      resource: "https://mcp.example.com/",
+    });
+
+    const params = new URLSearchParams(capturedBody);
+    expect(capturedHeaders.Authorization).toBe(
+      `Basic ${Buffer.from("client-xyz:secret-xyz").toString("base64")}`,
+    );
+    expect(params.get("client_id")).toBeNull();
+    expect(params.get("client_secret")).toBeNull();
+    expect(params.get("grant_type")).toBe("refresh_token");
+    expect(params.get("refresh_token")).toBe("rt-abc");
+  });
+});
+
 // ─── computeExpiresAt ────────────────────────────────────────────────────────
 
 describe("computeExpiresAt", () => {

package/src/tests/memory-http-recall-gating.test.ts

@@ -26,6 +26,7 @@ const memory: AgentMemory = {
   name: "ui-memory-fixture",
   scope: "agent",
   source: "manual",
+  summary: null,
   sourcePath: null,
   sourceTaskId: null,
   chunkIndex: 0,
@@ -34,6 +35,7 @@ const memory: AgentMemory = {
   contextKey: null,
   createdAt: new Date("2026-06-14T00:00:00.000Z").toISOString(),
   updatedAt: new Date("2026-06-14T00:00:00.000Z").toISOString(),
+  accessedAt: new Date("2026-06-14T00:00:00.000Z").toISOString(),
 };
 
 mock.module("../be/memory", () => ({

package/src/tests/openapi-response-contract.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test } from "bun:test";
+import type { ServerResponse } from "node:http";
+import { z } from "zod";
+import { auditRouteResponses } from "../../scripts/check-openapi-response-coverage";
+import { route } from "../http/route-def";
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+interface Captured {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: string;
+}
+
+function fakeRes(captured: Captured): ServerResponse {
+  return {
+    writeHead(status: number, headers: Record<string, string>) {
+      captured.status = status;
+      captured.headers = headers;
+      return this;
+    },
+    end(chunk?: unknown) {
+      captured.body = typeof chunk === "string" ? chunk : undefined;
+      return this;
+    },
+  } as unknown as ServerResponse;
+}
+
+const testRoute = route({
+  method: "get",
+  path: "/api/__respond-contract-test",
+  pattern: ["api", "__respond-contract-test"],
+  summary: "respond() contract fixture",
+  tags: ["Tests"],
+  responses: {
+    200: {
+      description: "ok",
+      schema: z.object({ name: z.string(), count: z.number().int() }),
+    },
+  },
+});
+
+// ─── respond() egress contract ───────────────────────────────────────────────
+
+describe("route handle respond()", () => {
+  test("valid payload: exact status, JSON content-type, raw JSON.stringify body", () => {
+    const captured: Captured = {};
+    const payload = { name: "swarm", count: 3 };
+    testRoute.respond(fakeRes(captured), 200, payload);
+
+    expect(captured.status).toBe(200);
+    expect(captured.headers).toEqual({ "Content-Type": "application/json" });
+    // Wire bytes are the RAW payload, never the schema's parsed output.
+    expect(captured.body).toBe(JSON.stringify(payload));
+  });
+
+  test("invalid payload throws a schema-violation error under bun test (NODE_ENV=test)", () => {
+    const captured: Captured = {};
+    expect(() =>
+      // biome-ignore lint/suspicious/noExplicitAny: deliberately violating the compile-time contract
+      testRoute.respond(fakeRes(captured), 200, { name: 42 } as any),
+    ).toThrow(/Response schema violation: GET \/api\/__respond-contract-test 200/);
+    // Nothing was written — the throw happens before writeHead.
+    expect(captured.status).toBeUndefined();
+  });
+
+  test("validation is OFF when NODE_ENV is unset (production posture): invalid payload still sends", () => {
+    // VALIDATE_RESPONSES is baked at module load, so probe in a subprocess
+    // with a production-like env (NODE_ENV deliberately unset on deploys).
+    const probe = `
+      import { z } from "zod";
+      import { route } from "${import.meta.dir}/../http/route-def";
+      const r = route({
+        method: "get", path: "/probe", pattern: ["probe"], summary: "p", tags: ["t"],
+        responses: { 200: { description: "ok", schema: z.object({ n: z.number() }) } },
+      });
+      let status = 0, body = "";
+      r.respond({ writeHead(s) { status = s; return this; }, end(b) { body = b; return this; } }, 200, { n: "not-a-number" });
+      console.log(JSON.stringify({ status, body }));
+    `;
+    const env = { ...process.env };
+    delete env.NODE_ENV;
+    delete env.VALIDATE_HTTP_RESPONSES;
+    const proc = Bun.spawnSync(["bun", "-e", probe], { env });
+    expect(proc.exitCode).toBe(0);
+    const out = JSON.parse(proc.stdout.toString().trim());
+    expect(out.status).toBe(200);
+    expect(out.body).toBe(JSON.stringify({ n: "not-a-number" }));
+  });
+});
+
+// ─── coverage-gate audit (per-status regression) ─────────────────────────────
+
+describe("auditRouteResponses", () => {
+  test("a NEW undecided 2xx on a partially-covered route is reported per status code", () => {
+    // Regression for the route-level-exemption hole (codex review, PR #1141):
+    // a backlogged/covered route gaining a fresh untyped 201 must surface it.
+    const { undecided } = auditRouteResponses([
+      {
+        method: "post",
+        path: "/api/things",
+        responses: {
+          200: { description: "ok", schema: z.object({}) },
+          201: { description: "created" }, // no decision
+        },
+      },
+    ] as never);
+    expect(undecided).toEqual(["POST /api/things 201"]);
+  });
+
+  test("bodiless 204/205 and non-2xx codes need no decision; unstructured counts as decided", () => {
+    const { undecided } = auditRouteResponses([
+      {
+        method: "get",
+        path: "/api/stream",
+        responses: {
+          200: { description: "sse", unstructured: "SSE stream" },
+          204: { description: "no content" },
+          404: { description: "not found" },
+        },
+      },
+    ] as never);
+    expect(undecided).toEqual([]);
+  });
+
+  test("schema + unstructured on the same response is a contradiction", () => {
+    const { contradictory } = auditRouteResponses([
+      {
+        method: "get",
+        path: "/api/confused",
+        responses: {
+          200: { description: "??", schema: z.object({}), unstructured: "also raw" },
+        },
+      },
+    ] as never);
+    expect(contradictory).toEqual(["GET /api/confused 200"]);
+  });
+});