chore: file header and forwarding mocks on the new tests (#2319 round 10)

requestTimeout.test.ts had no file-level header, which AGENTS.md
requires of every file; it now explains what each group of cases pins
and why, including why the composition cases are written as a contrast.

The two mock fetches I added used `as unknown as typeof fetch`, which
AGENTS.md rules out without an inline justification. A contextually
typed forwarding function keeps the vitest mock inspectable and needs
no cast at all.

The PR description still described the pre-fix cancellation flow; it is
rewritten to say that the signal now reaches the backend's outbound
fetch and what the race is still for.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YFnM6RqB4nXqNysgUYmjmq
Signed-off-by: cliffhall <cliff@futurescale.com>

clients/web/src/test/core/auth/requestTimeout.test.ts

@@ -1,3 +1,26 @@
+/**
+ * Unit coverage for `withOAuthRequestTimeout` (#2319) — the deadline every
+ * OAuth-path request runs under.
+ *
+ * What is pinned here, and why each case exists rather than being obvious:
+ *
+ * - **The bound itself**, including the *body*: `fetch` resolves on headers, so
+ *   a server that sends them and then stalls has to be caught by the buffering
+ *   race, not by the fetch promise.
+ * - **The rebuilt response.** Buffering means the caller gets a different
+ *   `Response` object, so `url` / `redirected` / `type` are asserted to survive
+ *   and `content-encoding` / `content-length` to be dropped — the buffer holds
+ *   the decoded body, which makes both of those headers lies.
+ * - **Cancellation semantics.** The caller's signal is forwarded *and* raced,
+ *   so the tests distinguish the two: one uses a fetch that honours the signal,
+ *   another uses one that ignores it entirely.
+ * - **Composition with `withRfc8414OidcCompat`**, written as a contrast between
+ *   the two orderings. It is the ordering that is under test, not one
+ *   arrangement's behaviour, so the wrong one is asserted to misattribute.
+ *
+ * Fake timers throughout: every budget here is exercised by advancing the clock
+ * rather than by waiting, so the suite costs milliseconds.
+ */
 import { describe, it, expect, vi, afterEach } from "vitest";
 import {
   DEFAULT_OAUTH_REQUEST_TIMEOUT_MS,

clients/web/src/test/core/mcp/remote/createRemoteFetch.test.ts

@@ -183,7 +183,9 @@ describe("createRemoteFetch", () => {
         .mockResolvedValue(ok(standardRemoteBody));
       const remoteFetch = createRemoteFetch({
         baseUrl: "http://remote.example",
-        fetchFn: fetchFn as unknown as typeof fetch,
+        // A contextually typed forwarding function rather than a double cast:
+        // the mock stays inspectable and nothing bypasses the type system.
+        fetchFn: (input, init) => fetchFn(input, init),
       });
       return { fetchFn, remoteFetch };
     }
@@ -256,7 +258,8 @@ describe("createRemoteFetch", () => {
       );
       return createRemoteFetch({
         baseUrl: "http://remote.example",
-        fetchFn: fetchFn as unknown as typeof fetch,
+        // Forwarding function, not a double cast — see `capture` above.
+        fetchFn: (input, init) => fetchFn(input, init),
       });
     }