@bevel-software/platform-core-backend 0.13.5 → 0.14.0

package/src/modules/connection-probe/index.ts

@@ -0,0 +1,2 @@
+export * from './connection-probe.contract.js';
+export { ConnectionProbeService } from './connection-probe.service.js';

package/src/modules/diff/diff.routes.ts

@@ -3,7 +3,7 @@ import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared
 import type { IDiffService } from './diff.interface.js';
 import type { AuthService } from '../auth/auth.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
+import { canReadWorkspacePath, toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
 import { WorkflowDomainError, WorkflowValidationError } from '../../shared/domain-errors.js';
 import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
@@ -138,10 +138,14 @@ export function createDiffRoutes(
   }
 
   /** Read gate for a single change path (mirrors GET /review/file). Returns true to proceed. */
-  async function canReadPath(workspaceId: string, email: string, pathParam: string): Promise<boolean> {
-    const rel = toKbRelative(pathParam, kbDirName);
-    // Non-KB paths (toKbRelative → null) carry no read rules and pass.
-    return rel === null || (await accessControl.canRead(workspaceId, email, rel));
+  function canReadPath(workspaceId: string, email: string, pathParam: string): Promise<boolean> {
+    return canReadWorkspacePath(
+      (w, e, p) => accessControl.canRead(w, e, p),
+      workspaceId,
+      email,
+      kbDirName,
+      pathParam,
+    );
   }
 
   router.get('/workspace/:id/review', async (req, res) => {

package/src/modules/kb-fs/__tests__/mutex.test.ts

@@ -8,6 +8,113 @@ function deferred<T = void>() {
 }
 
 describe('WorkspaceMutex', () => {
+  describe('runAll', () => {
+    /**
+     * The property nesting cannot provide: `run(a, () => run(b, fn))` releases
+     * nothing, but between taking `a` and taking `b` the second key is free,
+     * so a single-key task can slip in, run to completion, and be gone before
+     * the pair operation's body starts. `runAll` reserves the set in one
+     * synchronous step, so it cannot be interleaved that way.
+     */
+    it('reserves every key before any of them can be taken by another task', async () => {
+      const mtx = new WorkspaceMutex();
+      const order: string[] = [];
+      const release = deferred();
+
+      // Something already holds 'a', so the pair operation cannot start yet —
+      // this is the window a nested acquisition would leave 'b' open in.
+      const holder = mtx.run('a', async () => {
+        order.push('holder-start');
+        await release.promise;
+        order.push('holder-end');
+      });
+      await new Promise((r) => setImmediate(r));
+
+      const pair = mtx.runAll(['a', 'b'], async () => {
+        order.push('pair');
+      });
+      // Submitted while the pair is still waiting on 'a'. If 'b' were taken
+      // only after 'a' were granted, this would run first.
+      const single = mtx.run('b', async () => {
+        order.push('single-b');
+      });
+
+      release.resolve();
+      await Promise.all([holder, pair, single]);
+      expect(order).toEqual(['holder-start', 'holder-end', 'pair', 'single-b']);
+    });
+
+    it('lets a task on an unrelated key run in parallel', async () => {
+      const mtx = new WorkspaceMutex();
+      const order: string[] = [];
+      const release = deferred();
+
+      const holder = mtx.run('a', async () => {
+        await release.promise;
+        order.push('holder');
+      });
+      await new Promise((r) => setImmediate(r));
+
+      const pair = mtx.runAll(['a', 'b'], async () => void order.push('pair'));
+      const other = mtx.run('c', async () => void order.push('other'));
+
+      await other;
+      expect(order).toEqual(['other']);
+      release.resolve();
+      await Promise.all([holder, pair]);
+      expect(order).toEqual(['other', 'holder', 'pair']);
+    });
+
+    /**
+     * A failing task on ONE key must not release the others. `Promise.all`
+     * settles on the first rejection rather than waiting for the rest, so
+     * combining the predecessors without catching each one first would start
+     * this task while another key was still held.
+     */
+    it('waits for every predecessor even when one of them fails first', async () => {
+      const mtx = new WorkspaceMutex();
+      const order: string[] = [];
+      const failA = deferred();
+      const finishB = deferred();
+
+      const failing = mtx.run('a', async () => {
+        await failA.promise;
+        throw new Error('a-failed');
+      });
+      failing.catch(() => undefined); // handled below; keep the rejection quiet
+      const running = mtx.run('b', async () => {
+        await finishB.promise;
+        order.push('b-end');
+      });
+
+      // Queued while BOTH predecessors are still pending.
+      const pair = mtx.runAll(['a', 'b'], async () => void order.push('pair'));
+
+      failA.resolve();
+      await expect(failing).rejects.toThrow('a-failed');
+      await new Promise((r) => setImmediate(r));
+      // 'a' has failed, but 'b' still holds its key — the pair must wait.
+      expect(order).toEqual([]);
+
+      finishB.resolve();
+      await Promise.all([running, pair]);
+      expect(order).toEqual(['b-end', 'pair']);
+    });
+
+    it('releases every key when the body throws', async () => {
+      const mtx = new WorkspaceMutex();
+      await expect(mtx.runAll(['a', 'b'], async () => { throw new Error('boom'); })).rejects.toThrow('boom');
+      // Both keys must be usable again, or one failure wedges them forever.
+      await expect(mtx.run('a', async () => 'a-ok')).resolves.toBe('a-ok');
+      await expect(mtx.run('b', async () => 'b-ok')).resolves.toBe('b-ok');
+    });
+
+    it('collapses a duplicate key instead of waiting on itself', async () => {
+      const mtx = new WorkspaceMutex();
+      await expect(mtx.runAll(['a', 'a'], async () => 'done')).resolves.toBe('done');
+    });
+  });
+
   it('serializes tasks for the same key in submission order', async () => {
     const mtx = new WorkspaceMutex();
     const order: string[] = [];

package/src/modules/kb-fs/mutex.ts

@@ -8,14 +8,59 @@ export class WorkspaceMutex {
   private readonly tails = new Map<string, Promise<unknown>>();
 
   async run<T>(key: string, fn: () => Promise<T>): Promise<T> {
-    const prev = this.tails.get(key) ?? Promise.resolve();
-    const next = prev.catch(() => undefined).then(fn);
-    this.tails.set(key, next);
+    return this.runAll([key], fn);
+  }
+
+  /**
+   * Reserve SEVERAL keys for one operation, atomically.
+   *
+   * Nesting `run(a, () => run(b, fn))` does NOT do this: between taking `a`
+   * and taking `b` there is a gap in which another operation can take `b`,
+   * finish, and release it — so an operation holding both keys can still be
+   * interleaved with one holding just the second. For branch lifecycle that
+   * gap is the whole bug: a change request being opened `Y -> X` would hold
+   * one branch's key while the other was deleted out from under it.
+   *
+   * This reserves the set in ONE synchronous step. The tails are read and
+   * rewritten without an await between, so no other call can observe a
+   * half-taken set: a concurrent `run` on any of these keys either already
+   * sits in `prev` (it goes first) or chains onto `next` (it goes after).
+   * Within one call nothing is ever held while waiting for something else,
+   * so callers that do not nest need no ordering discipline and cannot
+   * deadlock.
+   *
+   * NESTING is the one way to reintroduce hold-and-wait, so never nest
+   * `run`/`runAll` calls on the same instance. An inner call chains behind
+   * everything already queued on its keys, which can include a `runAll` that
+   * is itself waiting for the outer call to finish: `run(b, () => run(a, …))`
+   * was harmless when every operation took a single key, but against a
+   * concurrent `runAll([a, b])` it deadlocks — outer waits inner, inner
+   * waits the pair, the pair waits outer. No caller nests today; keep it
+   * that way, or hand the full key set to one `runAll` at the top.
+   *
+   * Duplicate keys collapse; the operation waits on each distinct key once.
+   *
+   * Each predecessor is caught INDIVIDUALLY, before the `Promise.all`. A bare
+   * `Promise.all` settles on the first rejection rather than waiting for the
+   * rest, so one key's task failing early would start this one while another
+   * key was still held — a failure on any key would punch a hole in the
+   * mutual exclusion of every key beside it. Catching first makes the
+   * combined promise wait for all of them to settle, however each ends.
+   */
+  async runAll<T>(keys: string[], fn: () => Promise<T>): Promise<T> {
+    const distinct = [...new Set(keys)];
+    const prev = Promise.all(
+      distinct.map((k) => (this.tails.get(k) ?? Promise.resolve()).catch(() => undefined)),
+    );
+    const next = prev.then(fn);
+    for (const k of distinct) this.tails.set(k, next);
     try {
       return await next;
     } finally {
-      if (this.tails.get(key) === next) {
-        this.tails.delete(key);
+      for (const k of distinct) {
+        if (this.tails.get(k) === next) {
+          this.tails.delete(k);
+        }
       }
     }
   }

package/src/modules/mcp/__tests__/mcp-routes-harness.ts

@@ -0,0 +1,89 @@
+import type { Server as HttpServer } from 'node:http';
+import type { RequestHandler } from 'express';
+import express from 'express';
+import { createMcpRoutes } from '../mcp.routes.js';
+
+/**
+ * The shared mount for every `createMcpRoutes` suite.
+ *
+ * Three suites exercise different slices of this router — the transport's
+ * session routing, the connection-key routes, the local-token exchange — and
+ * each had grown its own copy of the same scaffolding: a `fakeAuth` stand-in,
+ * an `app.listen(0)` plus `afterEach` close, and the eight-argument
+ * `createMcpRoutes` call with stubs in every position the suite does not care
+ * about. Three copies meant a signature change had three places to patch, and
+ * they had already drifted from one another.
+ *
+ * Not collected by vitest: the include pattern is `**\/*.test.ts`, and this is
+ * not a test file.
+ */
+
+/**
+ * Auth stand-in binding the user named by `x-test-user`, defaulting to user-A.
+ *
+ * The header lets a suite act as a second user (the cross-user checks need
+ * one); suites that never send it see the single fixed user their assertions
+ * were written against.
+ */
+export const fakeAuth: RequestHandler = (req, _res, next) => {
+  req.userId = (req.headers['x-test-user'] as string | undefined) ?? 'user-A';
+  next();
+};
+
+/**
+ * The collaborators a suite actually cares about. Anything omitted is stubbed:
+ * `createMcpRoutes` only dereferences a dependency inside the handler that
+ * needs it, so a suite that never calls that route never touches the stub.
+ */
+export interface McpRoutesDeps {
+  mcpService?: unknown;
+  externalApiKeyService?: unknown;
+  llmUsageService?: unknown;
+  internalTokens?: unknown;
+  oauthProvider?: unknown;
+  resourceMetadataUrl?: string;
+}
+
+/** Servers opened by `mountMcpRoutes`, closed together by `closeMountedRoutes`. */
+const openServers = new Set<HttpServer>();
+
+/**
+ * Mount the router on an ephemeral port; returns its base URL. Every mount is
+ * tracked, so a suite's teardown is one `closeMountedRoutes()` regardless of
+ * how many it opened.
+ */
+export async function mountMcpRoutes(deps: McpRoutesDeps = {}): Promise<string> {
+  const stub = {} as never;
+  const app = express();
+  app.use(express.json());
+  app.use(
+    '/api',
+    createMcpRoutes(
+      // `createMcpRoutes` calls `onSessionEvicted` at CONSTRUCTION, so unlike
+      // the others this one needs a real function even when unused.
+      (deps.mcpService ?? { onSessionEvicted: () => {} }) as never,
+      (deps.externalApiKeyService ?? stub) as never,
+      fakeAuth,
+      fakeAuth,
+      (deps.llmUsageService ?? stub) as never,
+      (deps.internalTokens ?? stub) as never,
+      (deps.oauthProvider ?? stub) as never,
+      deps.resourceMetadataUrl ?? '',
+    ),
+  );
+  const server = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  openServers.add(server);
+  const { port } = server.address() as { port: number };
+  return `http://127.0.0.1:${port}`;
+}
+
+/** Close every server this harness opened. Safe to call when none are open. */
+export async function closeMountedRoutes(): Promise<void> {
+  const servers = [...openServers];
+  openServers.clear();
+  await Promise.all(
+    servers.map((s) => new Promise<void>((resolve) => s.close(() => resolve()))),
+  );
+}

package/src/modules/mcp/__tests__/mcp.routes.delete.test.ts

@@ -1,10 +1,7 @@
-import type { Server as HttpServer } from 'node:http';
-import type { RequestHandler } from 'express';
-import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { createMcpRoutes } from '../mcp.routes.js';
 import { TokenNotFoundError, TokenStillActiveError } from '../../tool-auth/external-api-key.errors.js';
 import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
+import { closeMountedRoutes, mountMcpRoutes } from './mcp-routes-harness.js';
 
 /**
  * Focused coverage for the status mapping of
@@ -14,19 +11,8 @@ import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.in
  * HTTP status codes (404 / 409 / 500) and the success shape.
  */
 
-// Stand-in auth: bind a user like the real jwtAuthMiddleware does.
-const fakeAuth: RequestHandler = (req, _res, next) => {
-  req.userId = 'user-A';
-  next();
-};
-
-let httpServer: HttpServer | undefined;
-
 afterEach(async () => {
-  if (httpServer) {
-    await new Promise<void>((resolve) => httpServer!.close(() => resolve()));
-    httpServer = undefined;
-  }
+  await closeMountedRoutes();
   vi.restoreAllMocks();
 });
 
@@ -35,24 +21,10 @@ async function mountWithRemove(
 ): Promise<{ baseUrl: string; remove: ReturnType<typeof vi.fn> }> {
   const spy = vi.fn(remove);
   const externalApiKeyService = { remove: spy } as unknown as IExternalApiKeyService;
-  // createMcpRoutes only touches mcpService.onSessionEvicted at construction.
-  const mcpService = { onSessionEvicted: () => {} } as never;
-  const stub = {} as never;
-
-  const app = express();
-  app.use(express.json());
-  // local-token deps (internal tokens / OAuth provider / metadata URL) are only
-  // dereferenced by that route's handler — stubs suffice here.
-  app.use(
-    '/api',
-    createMcpRoutes(mcpService, externalApiKeyService, fakeAuth, fakeAuth, stub, stub, stub, ''),
-  );
-
-  httpServer = await new Promise<HttpServer>((resolve) => {
-    const s = app.listen(0, () => resolve(s));
-  });
-  const port = (httpServer.address() as { port: number }).port;
-  return { baseUrl: `http://127.0.0.1:${port}`, remove: spy };
+  // The local-token deps (internal tokens / OAuth provider / metadata URL) are
+  // only dereferenced by that route's handler, so the harness's stubs suffice.
+  const baseUrl = await mountMcpRoutes({ externalApiKeyService });
+  return { baseUrl, remove: spy };
 }
 
 async function del(baseUrl: string, id: string): Promise<Response> {

package/src/modules/mcp/__tests__/mcp.routes.local-token.test.ts

@@ -1,14 +1,11 @@
-import type { Server as HttpServer } from 'node:http';
-import type { RequestHandler } from 'express';
-import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
-import { createMcpRoutes } from '../mcp.routes.js';
 import { MCP_LOOPBACK_TOKEN_TTL_MS } from '../mcp.service.js';
 import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
 import { createTokenVerifier } from '../../tool-auth/tool-auth.middleware.js';
 import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
 import type { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
+import { closeMountedRoutes, mountMcpRoutes } from './mcp-routes-harness.js';
 
 /**
  * Coverage for POST /api/mcp/local-token — the OAuth-access-token → internal
@@ -31,19 +28,8 @@ import type { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
 
 const RESOURCE_METADATA_URL = 'https://bevel.example/.well-known/oauth-protected-resource/api/mcp';
 
-// Stand-in for routes this suite never exercises.
-const fakeAuth: RequestHandler = (req, _res, next) => {
-  req.userId = 'user-A';
-  next();
-};
-
-let httpServer: HttpServer | undefined;
-
 afterEach(async () => {
-  if (httpServer) {
-    await new Promise<void>((resolve) => httpServer!.close(() => resolve()));
-    httpServer = undefined;
-  }
+  await closeMountedRoutes();
   vi.restoreAllMocks();
 });
 
@@ -69,31 +55,13 @@ async function mount(oauth: BevelOAuthProvider): Promise<{
   const externalApiKeyService = {
     looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
   } as unknown as IExternalApiKeyService;
-  // createMcpRoutes only touches mcpService.onSessionEvicted at construction.
-  const mcpService = { onSessionEvicted: () => {} } as never;
-  const stub = {} as never;
-
-  const app = express();
-  app.use(express.json());
-  app.use(
-    '/api',
-    createMcpRoutes(
-      mcpService,
-      externalApiKeyService,
-      fakeAuth,
-      fakeAuth,
-      stub,
-      internalTokens,
-      oauth,
-      RESOURCE_METADATA_URL,
-    ),
-  );
-
-  httpServer = await new Promise<HttpServer>((resolve) => {
-    const s = app.listen(0, () => resolve(s));
+  const baseUrl = await mountMcpRoutes({
+    externalApiKeyService,
+    internalTokens,
+    oauthProvider: oauth,
+    resourceMetadataUrl: RESOURCE_METADATA_URL,
   });
-  const port = (httpServer.address() as { port: number }).port;
-  return { baseUrl: `http://127.0.0.1:${port}`, internalTokens };
+  return { baseUrl, internalTokens };
 }
 
 async function exchange(baseUrl: string, authorization?: string): Promise<Response> {

package/src/modules/mcp/__tests__/mcp.routes.session.test.ts

@@ -0,0 +1,226 @@
+import type { Request as ExpressRequest, Response as ExpressResponse } from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { closeMountedRoutes, mountMcpRoutes } from './mcp-routes-harness.js';
+
+/**
+ * Session routing on the MCP transport routes — how `/api/mcp` answers a
+ * request whose `Mcp-Session-Id` it cannot resolve.
+ *
+ * The distinction is load-bearing rather than cosmetic. Streamable HTTP makes
+ * HTTP 404 on a request bearing a session id the signal a client re-initializes
+ * on; 400 means "you sent something malformed", which has no recovery. These
+ * routes used to answer both misses — no session id, and a session id from a
+ * session that no longer exists — with one 400 on POST and one 404 on
+ * GET/DELETE, so a client whose session died with the server (a restart wipes
+ * the in-process map) was told its request was malformed and stayed stranded.
+ *
+ * Locked down here:
+ *   - the two misses map to distinct, spec-correct codes on every verb;
+ *   - both bodies are real JSON-RPC error objects, since this router answers
+ *     before the SDK transport that would otherwise have shaped them;
+ *   - an `initialize` carrying a STALE session id still opens a new session —
+ *     the recovery path itself, which the old "no session id" guard blocked;
+ *   - the live-session and cross-user branches are untouched.
+ */
+
+/** The id the FIRST session minted in a test gets; `openSession` establishes it. */
+const SESSION_ID = 'sess-1';
+
+afterEach(async () => {
+  await closeMountedRoutes();
+  vi.restoreAllMocks();
+});
+
+/**
+ * A createSession stub shaped like the real one: it hands back a transport
+ * whose `handleRequest` reports the session id it served, and announces the
+ * session through `onSessionInitialized` from INSIDE that first call — which
+ * is when the SDK transport really fires it, and the only ordering the route's
+ * `active.set` closure can observe without a TDZ error.
+ *
+ * Each call mints a DISTINCT id (`sess-1`, `sess-2`, …) rather than a constant.
+ * With a constant, a route that wrongly minted a second session answered with
+ * a body identical to the correct one, so "no second session" could only ever
+ * be asserted through the call count. Numbering them puts the mistake in the
+ * response itself: a reply naming `sess-2` IS the extra session.
+ */
+function makeMcpService() {
+  let minted = 0;
+  const createSession = vi.fn(
+    async (
+      userId: string,
+      _tokenId: string | null,
+      _bearer: string,
+      onSessionInitialized: (sessionId: string) => void,
+    ) => {
+      minted += 1;
+      const sessionId = `sess-${minted}`;
+      let announced = false;
+      const transport = {
+        sessionId,
+        onclose: undefined as undefined | (() => void),
+        handleRequest: vi.fn(async (_req: ExpressRequest, res: ExpressResponse) => {
+          if (!announced) {
+            announced = true;
+            onSessionInitialized(sessionId);
+          }
+          res.status(200).json({ forwarded: true, sessionId, userId });
+        }),
+        close: vi.fn(async () => {}),
+      };
+      const server = { connect: vi.fn(async () => {}), close: vi.fn(async () => {}) };
+      return { transport, server };
+    },
+  );
+  return { onSessionEvicted: () => {}, createSession };
+}
+
+async function mount(): Promise<{ baseUrl: string; createSession: ReturnType<typeof vi.fn> }> {
+  const mcpService = makeMcpService();
+  const baseUrl = await mountMcpRoutes({ mcpService });
+  return { baseUrl, createSession: mcpService.createSession };
+}
+
+const INITIALIZE = {
+  jsonrpc: '2.0',
+  id: 0,
+  method: 'initialize',
+  params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'c', version: '0' } },
+};
+const TOOL_CALL = { jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} };
+
+async function send(
+  baseUrl: string,
+  opts: { method?: string; sessionId?: string; body?: unknown; user?: string } = {},
+): Promise<Response> {
+  const { method = 'POST', sessionId, body, user } = opts;
+  return fetch(`${baseUrl}/api/mcp`, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+      ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
+      ...(user ? { 'x-test-user': user } : {}),
+    },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+}
+
+/** Open a real session so `active` holds SESSION_ID. */
+async function openSession(baseUrl: string): Promise<void> {
+  const res = await send(baseUrl, { body: INITIALIZE });
+  expect(res.status).toBe(200);
+}
+
+describe('POST /mcp session routing', () => {
+  it('answers an unknown session id with 404 / -32001, the re-initialize signal', async () => {
+    const { baseUrl } = await mount();
+    const res = await send(baseUrl, { sessionId: 'sess-from-before-the-restart', body: TOOL_CALL });
+    expect(res.status).toBe(404);
+    await expect(res.json()).resolves.toEqual({
+      jsonrpc: '2.0',
+      error: { code: -32001, message: 'Session not found' },
+      id: null,
+    });
+  });
+
+  it('answers a missing session id with 400 / -32000 — a different code from the miss above', async () => {
+    const { baseUrl } = await mount();
+    const res = await send(baseUrl, { body: TOOL_CALL });
+    expect(res.status).toBe(400);
+    await expect(res.json()).resolves.toEqual({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Bad Request: Mcp-Session-Id header is required' },
+      id: null,
+    });
+  });
+
+  it('opens a new session for an initialize that still carries a STALE session id', async () => {
+    const { baseUrl, createSession } = await mount();
+    // Exactly what a client does after a server restart: it re-initializes
+    // before it has any reason to drop the id it was given last time.
+    const res = await send(baseUrl, { sessionId: 'sess-from-before-the-restart', body: INITIALIZE });
+    expect(res.status).toBe(200);
+    await expect(res.json()).resolves.toMatchObject({ forwarded: true, sessionId: SESSION_ID });
+    expect(createSession).toHaveBeenCalledTimes(1);
+  });
+
+  it('opens a new session for an initialize with no session id', async () => {
+    const { baseUrl, createSession } = await mount();
+    const res = await send(baseUrl, { body: INITIALIZE });
+    expect(res.status).toBe(200);
+    expect(createSession).toHaveBeenCalledTimes(1);
+  });
+
+  it('forwards to the live transport once a session exists', async () => {
+    const { baseUrl, createSession } = await mount();
+    await openSession(baseUrl);
+    const res = await send(baseUrl, { sessionId: SESSION_ID, body: TOOL_CALL });
+    expect(res.status).toBe(200);
+    await expect(res.json()).resolves.toMatchObject({ forwarded: true, sessionId: SESSION_ID });
+    // No second session: the live branch was taken, not the initialize branch.
+    expect(createSession).toHaveBeenCalledTimes(1);
+  });
+
+  it('routes an initialize over a LIVE session to that session, minting no second one', async () => {
+    // The guard this pins is branch ORDER, and only this change made it
+    // load-bearing: `initialize` used to be gated on `!sessionIdHeader`, so
+    // the live-session branch and the initialize branch were mutually
+    // exclusive and their order did not matter. Without that gate, an
+    // initialize check placed first would match here too — and silently mint
+    // a second session over a working one, which is the failure the route
+    // comment and the PR both promise cannot happen.
+    //
+    // What is asserted is what this ROUTER owes: the request reached the
+    // existing transport and no new session was created. Rejecting a
+    // re-initialize is the SDK transport's own job (`-32600 Server already
+    // initialized`), and asserting that here would be asserting against the
+    // stub rather than against the code under test.
+    const { baseUrl, createSession } = await mount();
+    await openSession(baseUrl); // mints sess-1
+    const res = await send(baseUrl, { sessionId: SESSION_ID, body: INITIALIZE });
+    expect(res.status).toBe(200);
+    // sess-1, not sess-2: the live transport answered, not a fresh one.
+    await expect(res.json()).resolves.toMatchObject({ forwarded: true, sessionId: SESSION_ID });
+    expect(createSession).toHaveBeenCalledTimes(1);
+  });
+
+  it('still refuses another user’s live session with 403', async () => {
+    const { baseUrl } = await mount();
+    await openSession(baseUrl); // owned by user-A
+    const res = await send(baseUrl, { sessionId: SESSION_ID, body: TOOL_CALL, user: 'user-B' });
+    expect(res.status).toBe(403);
+    // JSON-RPC like every other answer this router gives before the SDK
+    // transport — a client parsing /api/mcp bodies as JSON-RPC must not hit a
+    // bare `{ error }` on this one branch.
+    await expect(res.json()).resolves.toEqual({
+      jsonrpc: '2.0',
+      error: { code: -32003, message: 'Session does not belong to this user' },
+      id: null,
+    });
+  });
+});
+
+describe.each(['GET', 'DELETE'])('%s /mcp session routing', (method) => {
+  it('answers an unknown session id with 404 / -32001', async () => {
+    const { baseUrl } = await mount();
+    const res = await send(baseUrl, { method, sessionId: 'sess-from-before-the-restart' });
+    expect(res.status).toBe(404);
+    await expect(res.json()).resolves.toEqual({
+      jsonrpc: '2.0',
+      error: { code: -32001, message: 'Session not found' },
+      id: null,
+    });
+  });
+
+  it('answers a missing session id with 400 / -32000', async () => {
+    const { baseUrl } = await mount();
+    const res = await send(baseUrl, { method });
+    expect(res.status).toBe(400);
+    await expect(res.json()).resolves.toEqual({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Bad Request: Mcp-Session-Id header is required' },
+      id: null,
+    });
+  });
+});