@gethmy/mcp 2.20.1 → 2.22.0

package/src/remote.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 /**
- * Remote MCP Server for Harmony
+ * Remote MCP Server for Harmony — stateless Streamable HTTP
  *
  * Hosted MCP endpoint that any AI agent can connect to via HTTP.
  * Auth via API key passed as Bearer token, validated against the Harmony API.
@@ -12,6 +12,107 @@
  * Env vars:
  *   HARMONY_API_URL - Harmony API base URL (default: https://app.gethmy.com/api)
  *   PORT            - Listen port (default: 3002)
+ *
+ * ## Why stateless (card #772)
+ *
+ * This server used to run the transport in *stateful* mode: `initialize` minted
+ * an `Mcp-Session-Id`, and a process-local `Map<sessionId, McpSession>` held the
+ * transport, `Server`, and API client for the life of the connection. That made
+ * the connection a dependency: a redeploy or restart of the Railway container
+ * dropped every session, and each client's next `tools/call` had to be answered
+ * with a spec-mandated 404 so it would re-`initialize` before it could work
+ * again. Session state was also a scaling ceiling — a second instance behind the
+ * same hostname cannot serve a session another instance minted.
+ *
+ * Now every HTTP request stands on its own:
+ *
+ * - `sessionIdGenerator: undefined` puts the SDK transport in stateless mode. No
+ *   session id is ever issued.
+ * - Because we issue none, *every* `Mcp-Session-Id` is by definition unknown, so
+ *   a non-initialize request carrying one is answered 404 (Streamable HTTP
+ *   §Session Management). That is a constant, not a lookup — no state is
+ *   consulted. It costs a client that handshook against the old stateful server
+ *   exactly one re-`initialize`, and buys back the handshake this server needs
+ *   for agent attribution (see `clientIdentities`). After it, no client ever
+ *   sends a session id again.
+ * - A fresh `Server` + transport is built per request. The SDK *requires* this:
+ *   reusing a stateless transport throws ("Stateless transport cannot be reused
+ *   across requests"), because JSON-RPC ids from different clients would collide
+ *   in its stream map. Construction is cheap — `registerHandlers` only installs
+ *   handlers over the module-level `TOOLS` table.
+ * - `initialize` is no longer a precondition. The SDK's `Server` gates on
+ *   declared capabilities, not on having seen a handshake, so a cold
+ *   `tools/list` or `tools/call` is served directly.
+ *
+ * ## What is still remembered, and why that is not session state
+ *
+ * `harmony_set_project_context` has to mean something on the *next* request, and
+ * ~28 tools default a missing `projectId`/`workspaceId` from it. So a small
+ * `UserContext` is kept, keyed by **OAuth grant** (`contextKey`, #774) — not by
+ * connection, not by session id:
+ *
+ * - `activeWorkspaceId` is re-derivable from the bearer alone (`/v1/auth/context`
+ *   returns the grant's primary workspace), so it is re-seeded from the token on
+ *   every request until an explicit `harmony_set_workspace_context` pins it.
+ * - `activeProjectId` has no server-side home today, so it lives here. Losing it
+ *   on restart is a strict improvement on the old behaviour, which lost it too —
+ *   *and* wedged the client with a 404 until it re-handshook.
+ * - One `auto-session` scope per **user** — deliberately coarser than the
+ *   context that registers it, because it governs which tracked sessions a card
+ *   switch ends, and one human working a card from two clients wants one session
+ *   on it, not two (see `getScopeId`). It gets a long-lived `sweepClient`
+ *   because the sweep fires minutes after any request.
+ *
+ * None of it is required to *serve* a request: an unknown grant is built from the
+ * bearer on the spot. It is remembered convenience, not a session.
+ *
+ * ### What is emphatically NOT shared: the API client
+ *
+ * `HarmonyApiClient.apiKey` is mutable and read at fetch time, so a client
+ * shared between requests can have its bearer swapped mid-flight by a sibling.
+ * For one user holding two OAuth grants that is a boundary break, not a
+ * nuisance: a request begun under grant A can complete under grant B's bearer,
+ * and `harmony-api`'s `isOAuthWorkspaceMismatch` — "the ONLY tenant boundary in
+ * the request" (#695) — sees a bearer that legitimately covers the workspace and
+ * lets it through. So every request builds its own client bound to the bearer
+ * that authenticated it, and reads workspace/project from a snapshot taken at
+ * request start (`buildRequestScope`). Nothing a sibling does can move either
+ * out from under an in-flight call.
+ *
+ * ### Why the key is the grant, not the user (#774)
+ *
+ * A stateless request carries exactly one identifier — the bearer — and a bearer
+ * rotates on refresh, so it cannot key anything long-lived. `userId` can, but it
+ * is *too coarse*: two MCP clients signed in as the same user would share what a
+ * per-connection server kept apart. `activeProjectId` was the visible symptom —
+ * Claude Desktop calling `harmony_set_project_context(P2)` moved where Claude
+ * Code's next `harmony_create_card` landed — and `clientIdentities` the quieter
+ * one, last-initializer-wins, so work auto-started by one client could be
+ * attributed to the other's name.
+ *
+ * Each client consents separately and so holds its own OAuth grant, which makes
+ * the grant exactly the right granularity: finer than the user, and — unlike the
+ * bearer — stable across rotation, because `oauth_tokens.token_family_id` is
+ * minted once at consent and carried through every refresh. `/v1/auth/context`
+ * returns it as `grantId`, and `contextKey` keys both maps on it, falling back
+ * to `userId` when there is no grant (legacy api_key, or an older harmony-api).
+ *
+ * Note what this was never about: authorization. The bearer and the workspace
+ * were already per-request, so `isOAuthWorkspaceMismatch` — "the ONLY tenant
+ * boundary in the request" (#695) — held before this change and holds after.
+ * What moved is correctness and attribution.
+ *
+ * Residual, and deliberate: the auto-session *scope* stays per user (see
+ * `getScopeId`), so its sessions can span two grants while it has only one
+ * client to end them with. The inactivity sweep uses the user's most recently
+ * used context (`liveContextForUser`); the reaper's final drain has no live
+ * context left to pick and falls back to whichever registered last. Either way,
+ * if that bearer's grant doesn't cover the swept card's workspace, harmony-api
+ * rejects the end call and `cleanup_stale_agent_sessions` closes the row once its
+ * grace elapses — 2h for these, since an MCP auto-session carries no `agent_id`
+ * and so takes `AGENT_SWEEP_INTERACTIVE_MS`, not the daemon's 30min (#771).
+ * Ending on the right bearer means tracking one per tracked session —
+ * deliberately out of scope here, and mitigated by that cron.
  */
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -22,6 +123,7 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { HarmonyApiClient } from "./api-client.js";
 import {
+  type ClientInfo,
   dropScope,
   initAutoSession,
   shutdownAllSessions,
@@ -50,12 +152,21 @@ interface TokenInfo {
   userId: string;
   workspaceId: string | null;
   source: "api_key" | "oauth";
+  /**
+   * The OAuth grant this bearer belongs to, or null when there isn't one to
+   * have: a legacy `hmy_*` api_key, or a harmony-api deployed before #774.
+   *
+   * Unlike the bearer it survives refresh rotation, which is what makes it a
+   * usable key for remembered state. See `contextKey`.
+   */
+  grantId: string | null;
 }
 
-// Tiny TTL cache for /v1/auth/context. A refresh storm (Claude rotates a
-// token, fires several queued tool calls in parallel) would otherwise hammer
-// harmony-api with identical lookups. 30s is short enough that revocation
-// propagates quickly, long enough to absorb any normal burst.
+// Tiny TTL cache for /v1/auth/context. Load-bearing now that the transport is
+// stateless: there is no session to inherit trust from, so EVERY request
+// validates its bearer. Without the cache, a client firing a burst of parallel
+// tool calls would hammer harmony-api with identical lookups. 30s is short
+// enough that revocation propagates quickly, long enough to absorb any burst.
 const TOKEN_CACHE_TTL_MS = 30_000;
 const TOKEN_CACHE_MAX = 1000;
 const tokenCache = new Map<string, { info: TokenInfo; expiresAt: number }>();
@@ -103,12 +214,20 @@ async function validateToken(token: string): Promise<TokenInfo | null> {
       userId: string;
       source: "api_key" | "oauth" | "jwt";
       workspaceId: string | null;
+      /**
+       * Optional on purpose (#774). This server and harmony-api deploy
+       * independently, so a running instance can be talking to an API that
+       * doesn't send the field yet — `contextKey` then falls back to `userId`
+       * and behaviour is exactly what it was before.
+       */
+      grantId?: string | null;
     };
     if (data.source === "jwt") return null; // JWT not allowed on MCP endpoint
     const info: TokenInfo = {
       userId: data.userId,
       workspaceId: data.workspaceId,
       source: data.source,
+      grantId: data.grantId ?? null,
     };
     tokenCache.set(fp, { info, expiresAt: now + TOKEN_CACHE_TTL_MS });
     evictTokenCacheLru();
@@ -146,178 +265,406 @@ async function resolveWorkspaceForLegacyKey(
 }
 
 // ---------------------------------------------------------------------------
-// Session management
+// The key remembered state lives under
+// ---------------------------------------------------------------------------
+/**
+ * `contextKey` — the OAuth grant, falling back to the user.
+ *
+ * Each MCP client consents separately and therefore holds its own grant, which
+ * makes the grant the natural boundary for "what this client remembers". And
+ * unlike the bearer — which rotates on every refresh — a grant id is stable for
+ * the grant's whole life, so it can key a long-lived map.
+ *
+ * The fallback covers the two cases with no grant to speak of: a legacy `hmy_*`
+ * api_key, and the deploy window where harmony-api hasn't shipped `grantId` yet.
+ * Both then collapse to one context per user, i.e. exactly the pre-#774
+ * behaviour.
+ *
+ * Deliberately NOT the auto-session scope id, which stays per-user — see
+ * `getScopeId` in `baseDeps` for why those two want different granularity.
+ */
+function contextKey(keyInfo: TokenInfo): string {
+  return keyInfo.grantId ?? keyInfo.userId;
+}
+
+// ---------------------------------------------------------------------------
+// Remembered MCP client identity (outlives a context reap)
 // ---------------------------------------------------------------------------
-interface McpSession {
-  transport: WebStandardStreamableHTTPServerTransport;
-  server: Server;
-  client: HarmonyApiClient;
-  apiKey: string;
-  // Bound at session creation. Re-checked on every token hot-swap so a leaked
-  // session ID can't be paired with a different user's bearer to ride someone
-  // else's session.
+/**
+ * `contextKey` → the `clientInfo` from that grant's last `initialize`.
+ *
+ * Kept OUTSIDE `UserContext` on purpose. A stateless `tools/call` carries no
+ * handshake, so `Server.getClientVersion()` is undefined there and auto-session
+ * would refuse to start a session rather than fabricate an "Unknown Agent" one
+ * (card #295, `auto-session.ts`). Identity therefore has to be remembered from
+ * the handshake — and remembered for longer than the context that reads it,
+ * because a grant reaped after 60min idle whose client is still running would
+ * otherwise come back anonymous and silently stop getting auto-sessions.
+ *
+ * Keyed per grant, not per user (#774): two clients signed in as one user each
+ * handshake under their own grant, so keying by user made this
+ * last-initializer-wins and let work auto-started by one be attributed to the
+ * other's name.
+ *
+ * Two short strings per grant, so the cap is generous; entries never expire.
+ */
+const CLIENT_IDENTITY_MAX = 5000;
+const clientIdentities = new Map<string, ClientInfo>();
+
+function rememberClientIdentity(key: string, info: ClientInfo): void {
+  // Refresh LRU position, then bound the map.
+  clientIdentities.delete(key);
+  clientIdentities.set(key, info);
+  if (clientIdentities.size > CLIENT_IDENTITY_MAX) {
+    const oldest = clientIdentities.keys().next().value;
+    if (oldest) clientIdentities.delete(oldest);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-grant context (keyed by `contextKey` — NOT per connection, NOT a session)
+// ---------------------------------------------------------------------------
+interface UserContext {
   userId: string;
+  /** The `userContexts` key this context lives under (see `contextKey`). */
+  contextKey: string;
+  /**
+   * The OAuth grant, or null for a legacy api_key / a pre-#774 harmony-api — in
+   * which case `contextKey` is the userId and this is one context per user.
+   */
+  grantId: string | null;
+  /**
+   * Client for the auto-session sweep ONLY — never for serving a request.
+   *
+   * The sweep ends idle sessions minutes after the request that registered the
+   * scope, so it needs a bearer that outlives any one request; its key is
+   * refreshed from the most recent request. Request handlers must NOT share it:
+   * `HarmonyApiClient.apiKey` is mutable and read at fetch time, so a sibling
+   * request rotating the key mid-flight would send its bearer on this request's
+   * call. Between two OAuth grants of one user that silently crosses the grant
+   * boundary `harmony-api` enforces, which is why every request builds its own
+   * client bound to the bearer that authenticated it.
+   */
+  sweepClient: HarmonyApiClient;
+  /** Stable deps for the sweep's end-of-session pipeline. Reads `ctx` directly. */
+  sweepDeps: ToolDeps;
   activeWorkspaceId: string | null;
   activeProjectId: string | null;
-  createdAt: number;
-  // Bumped on every request that touches the session. Drives stale-session GC
-  // so a session that's actively rotating tokens stays alive past the access
-  // token TTL — auth happens per-request via the Bearer header, the session
-  // itself is just a transport handle.
+  /**
+   * True once `harmony_set_workspace_context` pinned the workspace. Until then
+   * each request derives its workspace from its own token, so a second OAuth
+   * grant scoped to a different workspace isn't stuck on the first grant's.
+   */
+  workspacePinned: boolean;
   lastUsedAt: number;
-  // Set by HarmonyApiClient.onUnauthorized when the API rejects the cached
-  // token mid-session. The HTTP layer reads this after transport.handleRequest
-  // returns and converts the response to an HTTP 401 challenge so the OAuth
-  // client refreshes instead of caching a JSON-RPC error forever.
-  unauthorized: boolean;
 }
 
-const sessions = new Map<string, McpSession>();
-
-// Stale-session GC. Uses lastUsedAt (sliding window) instead of createdAt so
-// long-lived clients that refresh OAuth tokens periodically aren't killed at
-// the 1h mark just because their session was created an hour ago. 24h is an
-// upper bound — clients that go truly idle that long can re-handshake cheaply.
-const SESSION_IDLE_MAX_MS = 24 * 60 * 60 * 1000;
-setInterval(
-  () => {
-    const now = Date.now();
-    for (const [id, session] of sessions) {
-      if (now - session.lastUsedAt > SESSION_IDLE_MAX_MS) {
-        session.transport.close().catch(() => {});
-        sessions.delete(id);
-      }
-    }
-  },
-  30 * 60 * 1000,
-);
+/**
+ * A single request's view of the context.
+ *
+ * Reads are snapshotted at request start and writes go to both the snapshot and
+ * the shared context, so a concurrent sibling cannot change the workspace or
+ * project a request is already running against. Without this, a request begun
+ * under grant A could read a workspace another grant re-seeded mid-flight —
+ * harmony-api would reject the mismatch, but the request would fail for a reason
+ * that has nothing to do with the caller.
+ */
+interface RequestContextView {
+  workspaceId: string | null;
+  projectId: string | null;
+}
 
-function createSession(apiKey: string, keyInfo: TokenInfo): McpSession {
-  // unauthorized flag lives on a mutable holder so the HarmonyApiClient
-  // callback can flip it without a circular reference between the client and
-  // the session struct it lives on.
-  const authState = { unauthorized: false };
+const userContexts = new Map<string, UserContext>();
 
-  // Forward declare so onsessioninitialized can register the session.
-  let sessionRef: McpSession;
+/**
+ * The most-recently-used live context for a user, or null if they have none.
+ *
+ * Needed because `userContexts` is keyed per grant while the auto-session scope
+ * is per user, so one scope can be backed by several contexts. Both of the
+ * scope's long-lived hooks — the sweep's client and the end-of-session deps —
+ * resolve through this rather than closing over the context that happened to
+ * register them: that context may be reaped, or its bearer may have gone stale
+ * while a sibling grant is the one still making requests.
+ */
+function liveContextForUser(userId: string): UserContext | null {
+  let best: UserContext | null = null;
+  for (const candidate of userContexts.values()) {
+    if (candidate.userId !== userId) continue;
+    if (!best || candidate.lastUsedAt > best.lastUsedAt) best = candidate;
+  }
+  return best;
+}
 
-  const transport = new WebStandardStreamableHTTPServerTransport({
-    sessionIdGenerator: () => crypto.randomUUID(),
-    enableJsonResponse: true,
-    onsessioninitialized: (sid: string) => {
-      sessions.set(sid, sessionRef);
+/**
+ * Idle reaper for `userContexts`.
+ *
+ * The stateful server dropped a user's auto-session scope on `transport.onclose`
+ * — its signal that the last connection went away. Stateless has no close event,
+ * so without this the `userContexts` and `auto-session` `scopes` maps would grow
+ * one entry per distinct user forever, and any session still tracked would
+ * dangle "working" (the shape of card #301, Gap 1).
+ *
+ * 60 minutes sits above both auto-session bounds (10min inactivity end, 25min
+ * heartbeat window), so we only reap users the sweep has already finished with.
+ * The `cleanup_stale_agent_sessions` cron may have closed a dangling row before
+ * we get here; `shutdownAllSessions` is best-effort, so that race costs nothing.
+ * (Its grace for these is `AGENT_SWEEP_INTERACTIVE_MS` = 2h — an MCP
+ * auto-session has no `agent_id`, so the 30min daemon window never applies.
+ * Corrected after #771 widened it; the pairing this comment used to cite is the
+ * bug that card fixed.)
+ */
+const CONTEXT_IDLE_MAX_MS = 60 * 60 * 1000;
+const CONTEXT_SWEEP_INTERVAL_MS = 10 * 60 * 1000;
+
+export function reapIdleContexts(now: number = Date.now()): void {
+  for (const [key, ctx] of userContexts) {
+    if (now - ctx.lastUsedAt <= CONTEXT_IDLE_MAX_MS) continue;
+    userContexts.delete(key);
+    const { userId } = ctx;
+
+    // The auto-session scope is per USER while contexts are per grant, so a
+    // user holding two grants has two contexts over one scope. Tearing it down
+    // for an idle grant would end the sessions the *active* grant is still
+    // working — so leave it to whichever context is reaped last.
+    if (liveContextForUser(userId)) {
       console.log(
-        `[mcp] session=${sid} init user=${keyInfo.userId} src=${keyInfo.source}`,
+        `[mcp] context key=${key} reaped (idle); user=${userId} scope kept`,
       );
-    },
-  });
+      continue;
+    }
 
-  const server = new Server(
-    { name: "harmony-mcp-remote", version: "1.0.0" },
-    { capabilities: { tools: {}, resources: {} } },
-  );
+    // Pause anything still tracked, THEN drop the scope so the shared sweep
+    // stops walking it. Order matters — dropping first would orphan those
+    // sessions with no client left to end them.
+    shutdownAllSessions(userId)
+      .catch(() => {})
+      .finally(() => {
+        // `shutdownAllSessions` makes network round-trips, so a request can
+        // arrive meanwhile and build a fresh context — which registers the
+        // scope again. Dropping it then would leave `getOrCreateScope` to
+        // lazily recreate an empty one with null getters, and since
+        // `initAutoSession` now runs only on context creation, that user would
+        // get no auto-sessions until the next reap. Only drop what we reaped —
+        // and a rebuild under *any* of the user's grants counts.
+        if (!liveContextForUser(userId)) dropScope(userId);
+      });
+    console.log(`[mcp] context key=${key} user=${userId} reaped (idle)`);
+  }
+}
 
-  // Create per-session API client. onUnauthorized fires when harmony-api
-  // returns 401 — we mark the session so the HTTP layer can surface a real
-  // 401 + WWW-Authenticate challenge to the OAuth client.
-  const client = new HarmonyApiClient({
+const contextSweepTimer = setInterval(
+  () => reapIdleContexts(),
+  CONTEXT_SWEEP_INTERVAL_MS,
+);
+// Bookkeeping only — never a reason to hold the process open. Without this,
+// importing this module from a script or test runner hangs on exit.
+contextSweepTimer.unref?.();
+
+/** Deps shared by both paths. `getClient` and the context accessors differ. */
+function baseDeps(
+  userId: string,
+): Omit<
+  ToolDeps,
+  | "getClient"
+  | "getActiveProjectId"
+  | "getActiveWorkspaceId"
+  | "setActiveProject"
+  | "setActiveWorkspace"
+> {
+  return {
+    isConfigured: () => true,
+    getApiUrl: () => HARMONY_API_URL,
+    getMemoryDir: () => null, // No local filesystem in remote mode
+    getUserEmail: () => null,
+    saveConfig: () => {}, // No-op in remote mode
+    resetClient: () => {}, // No-op in remote mode
+    // Partition auto-session bookkeeping by user. The hosted server is
+    // multi-tenant: keying by userId stops two users on the same card from
+    // colliding on one shared auto-session entry (card #301, Gap 2).
+    //
+    // Deliberately still the USER, not the grant, even though remembered
+    // context moved to the grant in #774. This scope decides which tracked
+    // sessions a card switch ends and which ones the sweep can close, and both
+    // are properties of the person, not the client: one human working a card
+    // from two clients should hold ONE auto-session on it — attributed to
+    // whichever client started it — rather than two rows racing each other.
+    // Attribution is what needed per-grant granularity, and it gets it from
+    // `getClientInfo` below.
+    getScopeId: () => userId,
+  };
+}
+
+function createUserContext(apiKey: string, keyInfo: TokenInfo): UserContext {
+  const sweepClient = new HarmonyApiClient({
     apiKey,
     apiUrl: HARMONY_API_URL,
     onUnauthorized: () => {
-      authState.unauthorized = true;
-      // Drop any cached "OK" entry for this bearer so future validations
-      // re-hit harmony-api and see the rejection.
-      invalidateTokenCache(client.getApiKey());
+      // No request to challenge — the sweep runs on a timer. Just drop the
+      // cached "OK" for this bearer so the next validation re-hits harmony-api.
+      invalidateTokenCache(sweepClient.getApiKey());
     },
   });
 
-  const now = Date.now();
-  const session: McpSession = {
-    transport,
-    server,
-    client,
-    apiKey,
+  const ctx: UserContext = {
     userId: keyInfo.userId,
+    contextKey: contextKey(keyInfo),
+    grantId: keyInfo.grantId,
+    sweepClient,
+    // Replaced immediately below — deps must close over the finished object.
+    sweepDeps: null as unknown as ToolDeps,
     activeWorkspaceId: keyInfo.workspaceId,
     activeProjectId: null,
-    createdAt: now,
-    lastUsedAt: now,
-    get unauthorized() {
-      return authState.unauthorized;
-    },
-    set unauthorized(v: boolean) {
-      authState.unauthorized = v;
-    },
+    workspacePinned: false,
+    lastUsedAt: Date.now(),
   };
-  sessionRef = session;
 
-  const deps: ToolDeps = {
-    getClient: () => client,
-    isConfigured: () => true,
-    getActiveProjectId: () => session.activeProjectId,
-    getActiveWorkspaceId: () => session.activeWorkspaceId,
+  ctx.sweepDeps = {
+    ...baseDeps(ctx.userId),
+    getClient: () => ctx.sweepClient,
+    getActiveProjectId: () => ctx.activeProjectId,
+    getActiveWorkspaceId: () => ctx.activeWorkspaceId,
     setActiveProject: (id) => {
-      session.activeProjectId = id;
+      ctx.activeProjectId = id;
     },
     setActiveWorkspace: (id) => {
-      session.activeWorkspaceId = id;
+      ctx.activeWorkspaceId = id;
+      ctx.workspacePinned = true;
     },
-    getApiUrl: () => HARMONY_API_URL,
-    getMemoryDir: () => null, // No local filesystem in remote mode
-    getUserEmail: () => null,
-    saveConfig: () => {}, // No-op in remote mode
-    resetClient: () => {}, // No-op in remote mode
-    // Partition auto-session bookkeeping by user. The hosted server is
-    // multi-tenant: keying by userId stops two users on the same card from
-    // colliding on one shared auto-session entry (card #301, Gap 2).
-    getScopeId: () => keyInfo.userId,
   };
 
-  registerHandlers(server, deps);
-
   // Wire the inactivity sweep + end-of-session pipeline for this user's scope.
-  // The remote transport historically skipped initAutoSession entirely, so
-  // hosted auto-sessions never auto-ended on inactivity and the end pipeline
-  // never fired — they dangled "working" indefinitely (card #301, Gap 1).
-  // Now each connection registers its userId scope; the shared process timer
-  // sweeps it like stdio. Identity is resolved per-request via options.clientInfo
-  // in the pre-hook (card #297), so no clientInfoGetter is supplied here. Re-init
-  // by a second connection of the same user just refreshes the scope's client —
-  // both are equivalent, and per-scope state means it can't clobber other users.
+  // `clientInfoGetter` is what keeps agent attribution working now that a
+  // stateless `tools/call` carries no handshake to read identity from (#297).
+  //
+  // A second grant of the same user re-runs this for the SAME scope, and
+  // `initAutoSession` overwrites the callbacks it was given (last one wins). So
+  // the client getter must not close over `ctx`: this context can be reaped, or
+  // sit idle with a bearer nobody is refreshing, while the sibling grant is the
+  // one still working. Resolving through `liveContextForUser` per call keeps the
+  // sweep on the most recently used context instead.
+  //
+  // Known gap, and why it is left alone: in the reaper's teardown branch the
+  // user has no live context by construction, so the drain falls back to `ctx` —
+  // whichever context registered last, not necessarily the one whose grant owns
+  // the sessions being drained. Every candidate bearer is 60min+ idle there and
+  // may cover the wrong workspace, in which case harmony-api rejects the end
+  // call and `cleanup_stale_agent_sessions` closes the row after its 2h
+  // interactive grace (#771). Picking correctly would mean tracking a bearer per
+  // tracked session, which is a larger change than this card; see the residual
+  // note in the module doc.
+  //
+  // The identity getter is the one hook that must NOT resolve through
+  // `liveContextForUser` — "who is calling" is per grant, and a scope-level
+  // getter can only answer for one of them. It stays pinned to this context's
+  // own key as a best-effort fallback; the authoritative per-request answer is
+  // the `getClientInfo` dep in `buildRequestScope`, which `trackActivity`
+  // prefers over this.
   initAutoSession(
+    // `runEndSessionPipeline` ignores its deps argument today (it works purely
+    // off the client), so this passes the registering context's — no resolution
+    // to do until that signature starts reading them.
     async (endClient, cardId, status) => {
-      await runEndSessionPipeline(endClient, deps, cardId, status);
+      await runEndSessionPipeline(endClient, ctx.sweepDeps, cardId, status);
     },
-    () => client,
-    undefined,
-    keyInfo.userId,
+    () => (liveContextForUser(ctx.userId) ?? ctx).sweepClient,
+    () => clientIdentities.get(ctx.contextKey) ?? null,
+    ctx.userId,
   );
 
-  // Single cleanup path: fires on explicit DELETE, our evictSession,
-  // and the stale-session GC. Keeping onsessioninitialized + this onclose
-  // (instead of also wiring onsessionclosed) avoids double-logging on DELETE.
-  transport.onclose = () => {
-    if (transport.sessionId) {
-      sessions.delete(transport.sessionId);
-      // Reap this user's auto-session scope once their LAST live connection is
-      // gone — otherwise `scopes` grows unbounded (one stale client/deps closure
-      // per distinct user) on a long-lived multi-tenant process. A user with
-      // another open connection keeps the scope (sessions.delete already ran, so
-      // the closing session isn't counted). Pause any in-flight auto-sessions so
-      // nothing dangles "working"; a reconnect + next tool call starts fresh.
-      const stillLive = [...sessions.values()].some(
-        (s) => s.userId === session.userId,
-      );
-      if (!stillLive) {
-        shutdownAllSessions(session.userId)
-          .catch(() => {})
-          .finally(() => dropScope(session.userId));
-      }
-      console.log(`[mcp] session=${transport.sessionId} closed`);
-    }
+  userContexts.set(ctx.contextKey, ctx);
+  console.log(
+    `[mcp] context key=${ctx.contextKey} user=${ctx.userId} created src=${keyInfo.source} grant=${ctx.grantId ?? "none"}`,
+  );
+  return ctx;
+}
+
+/**
+ * Build the client, view, and deps for one request.
+ *
+ * The client is bound to the bearer that authenticated *this* request and is
+ * never shared, so no sibling can swap the key out from under an in-flight
+ * fetch. `onUnauthorized` therefore latches directly on this request — no
+ * cross-request attribution problem to solve.
+ */
+function buildRequestScope(
+  ctx: UserContext,
+  apiKey: string,
+  keyInfo: TokenInfo,
+): { deps: ToolDeps; authState: { unauthorized: boolean } } {
+  const authState = { unauthorized: false };
+
+  const client = new HarmonyApiClient({
+    apiKey,
+    apiUrl: HARMONY_API_URL,
+    onUnauthorized: () => {
+      authState.unauthorized = true;
+      invalidateTokenCache(apiKey);
+    },
+  });
+
+  // Snapshot. An unpinned workspace comes from THIS request's grant, so two
+  // grants of one user never borrow each other's scope.
+  const view: RequestContextView = {
+    workspaceId: ctx.workspacePinned
+      ? ctx.activeWorkspaceId
+      : (keyInfo.workspaceId ?? ctx.activeWorkspaceId),
+    projectId: ctx.activeProjectId,
+  };
+
+  const deps: ToolDeps = {
+    ...baseDeps(ctx.userId),
+    getClient: () => client,
+    // Identity of the client on the other end of THIS request — i.e. of this
+    // grant. `trackActivity` prefers it over the scope-level getter, which one
+    // user's second grant would otherwise have overwritten (#774).
+    getClientInfo: () => clientIdentities.get(ctx.contextKey) ?? null,
+    getActiveProjectId: () => view.projectId,
+    getActiveWorkspaceId: () => view.workspaceId,
+    // Write through: the snapshot keeps this request consistent, the context
+    // carries the selection to the next one.
+    setActiveProject: (id) => {
+      view.projectId = id;
+      ctx.activeProjectId = id;
+    },
+    setActiveWorkspace: (id) => {
+      view.workspaceId = id;
+      ctx.activeWorkspaceId = id;
+      // An explicit choice outranks the token's primary workspace from here on.
+      ctx.workspacePinned = true;
+    },
   };
 
-  return session;
+  return { deps, authState };
+}
+
+async function resolveUserContext(
+  apiKey: string,
+  keyInfo: TokenInfo,
+): Promise<UserContext> {
+  const existing = userContexts.get(contextKey(keyInfo));
+  if (existing) {
+    existing.lastUsedAt = Date.now();
+    // Keep the sweep's bearer as fresh as the newest request. Safe to mutate
+    // because nothing serving a request reads this client — request handlers
+    // get their own, bound to their own bearer (see `buildRequestScope`).
+    existing.sweepClient.setApiKey(apiKey);
+    // Remember this token's grant workspace as the default for the *next*
+    // request that has none of its own. The request in hand doesn't read this
+    // — it derives its workspace from its own token in `buildRequestScope`.
+    if (!existing.workspacePinned && keyInfo.workspaceId) {
+      existing.activeWorkspaceId = keyInfo.workspaceId;
+    }
+    return existing;
+  }
+
+  // Legacy api_keys carry no workspace binding; fall back to the first
+  // workspace. Only on first sight of a user — an explicit
+  // harmony_set_workspace_context must not be re-seeded out from under them.
+  if (keyInfo.source === "api_key" && !keyInfo.workspaceId) {
+    keyInfo.workspaceId = await resolveWorkspaceForLegacyKey(apiKey);
+  }
+
+  return createUserContext(apiKey, keyInfo);
 }
 
 // ---------------------------------------------------------------------------
@@ -333,10 +680,12 @@ app.use(
     allowHeaders: [
       "Content-Type",
       "Authorization",
+      // Still allowed so a browser client that handshook against the old
+      // stateful server can deliver its stale id and get the 404 that tells it
+      // to re-initialize, rather than being blocked by CORS preflight.
       "Mcp-Session-Id",
       "Mcp-Protocol-Version",
     ],
-    exposeHeaders: ["Mcp-Session-Id"],
   }),
 );
 
@@ -345,7 +694,8 @@ app.get("/health", (c) =>
   c.json({
     status: "ok",
     service: "harmony-mcp-remote",
-    sessions: sessions.size,
+    mode: "stateless",
+    contexts: userContexts.size,
   }),
 );
 
@@ -388,12 +738,21 @@ function unauthenticatedResponse(
   );
 }
 
-// Per MCP spec (Streamable HTTP §3 / Session Management §3-4): when a client
-// presents an Mcp-Session-Id we don't recognize, we MUST return 404. Claude
-// then drops the session id and re-`initialize`s. Returning anything else
-// (e.g., transparently minting a new session) wedges the connection because
-// the body is a `tools/call`, not `initialize`, and the SDK transport will
-// reject it with `Server not initialized`.
+/**
+ * 404 for a non-initialize request that presents an `Mcp-Session-Id`.
+ *
+ * Streamable HTTP §Session Management: a session id the server does not
+ * recognise MUST be answered 404 so the client starts a new session. We issue
+ * none, so none is ever recognised — this is a constant, not a lookup, and
+ * consults no state.
+ *
+ * Only reachable from a client that handshook against the old stateful server.
+ * It costs that client one re-`initialize`, which is exactly what we want: the
+ * handshake is the only place `clientInfo` appears, and without it auto-session
+ * refuses to attribute work (see `clientIdentities`). Ignoring the header
+ * instead would leave every already-connected client anonymous — and therefore
+ * without auto-sessions — for as long as its process stayed alive.
+ */
 function sessionNotFound(sessionId: string): Response {
   return new Response(
     JSON.stringify({
@@ -411,41 +770,33 @@ function sessionNotFound(sessionId: string): Response {
   );
 }
 
-// Per spec: requests without an Mcp-Session-Id (other than initialization)
-// SHOULD return 400.
-function sessionRequiredResponse(): Response {
+/**
+ * 405 for the methods a stateless endpoint has nothing to do with.
+ *
+ * Streamable HTTP §2.2 explicitly sanctions this: a server that does not offer a
+ * server-initiated SSE stream answers GET with 405, and one that does not
+ * support client-terminated sessions answers DELETE with 405. Both hold here —
+ * responses are complete JSON (`enableJsonResponse`), and there is no session to
+ * terminate. Clients treat both as optional and carry on.
+ */
+function methodNotAllowed(message: string): Response {
   return new Response(
     JSON.stringify({
       jsonrpc: "2.0",
-      error: {
-        code: -32000,
-        message:
-          "Bad Request: Mcp-Session-Id header required for non-initialize requests",
-      },
+      error: { code: -32000, message },
       id: null,
     }),
     {
-      status: 400,
-      headers: { "Content-Type": "application/json" },
+      status: 405,
+      headers: { "Content-Type": "application/json", Allow: "POST" },
     },
   );
 }
 
-// Evict a session and tear down its transport. Used when an OAuth token
-// rotates or is revoked mid-session — we don't want to keep a zombie session
-// around with a stale cached api key.
-function evictSession(sessionId: string): void {
-  const session = sessions.get(sessionId);
-  if (!session) return;
-  sessions.delete(sessionId);
-  session.transport.close().catch(() => {});
-}
-
-// Best-effort body peek so we can route POSTs by JSON-RPC method without
+// Best-effort body peek so we can read `initialize` client identity without
 // double-reading the body downstream (transport.handleRequest accepts
 // `parsedBody` to skip its own json() call).
 async function peekBody(req: Request): Promise<unknown | undefined> {
-  if (req.method !== "POST") return undefined;
   const ct = req.headers.get("content-type") || "";
   if (!ct.includes("application/json")) return undefined;
   try {
@@ -455,11 +806,22 @@ async function peekBody(req: Request): Promise<unknown | undefined> {
   }
 }
 
-// MCP endpoint - handles POST (JSON-RPC), GET (SSE), DELETE (session close).
-// Mounted on both `/mcp` and `/` so clients that registered the bare host as
-// their server URL still reach the OAuth challenge instead of a 404.
+/** Pull `clientInfo` out of a validated `initialize` request body. */
+function extractClientInfo(body: unknown): ClientInfo | null {
+  const params = (body as { params?: { clientInfo?: unknown } }).params;
+  const info = params?.clientInfo as
+    | { name?: unknown; version?: unknown }
+    | undefined;
+  if (!info || typeof info.name !== "string" || !info.name) return null;
+  return {
+    name: info.name,
+    version: typeof info.version === "string" ? info.version : undefined,
+  };
+}
+
+// MCP endpoint. Mounted on both `/mcp` and `/` so clients that registered the
+// bare host as their server URL still reach the OAuth challenge, not a 404.
 const handleMcpRequest = async (c: import("hono").Context) => {
-  const method = c.req.method;
   const raw = c.req.raw;
 
   // 1. Bearer required for everything. No token → 401 + PRM challenge so
@@ -470,113 +832,98 @@ const handleMcpRequest = async (c: import("hono").Context) => {
   }
   const apiKey = authHeader.slice(7);
 
-  const sessionId = c.req.header("Mcp-Session-Id");
-
-  // 2. Existing session path — auth is per-request via the bearer; the
-  //    session ID is just a transport handle. Surviving token rotation here
-  //    is what keeps long-lived MCP connections alive past the 1h access
-  //    token TTL.
-  if (sessionId) {
-    const session = sessions.get(sessionId);
-
-    // Per MCP spec §3-4: unknown session id MUST return 404 so the client
-    // re-initializes. NEVER silently mint a new session — the body is a
-    // `tools/call`, not `initialize`, and we'd just bury the failure inside
-    // a JSON-RPC `Server not initialized` envelope. This was the bug
-    // surfacing as "Harmony MCP not responding" after a server restart or
-    // idle eviction.
-    if (!session) {
-      console.log(`[mcp] session=${sessionId} unknown → 404 re-init`);
-      return sessionNotFound(sessionId);
-    }
-
-    session.lastUsedAt = Date.now();
-
-    // Hot-swap the cached token when the OAuth client refreshed mid-session.
-    // Re-validate the new bearer and require it to belong to the same user
-    // before we accept it — otherwise a leaked session id paired with a
-    // different user's token would let an attacker ride the session.
-    if (session.apiKey !== apiKey) {
-      const fresh = await validateToken(apiKey);
-      if (!fresh) {
-        console.log(`[mcp] session=${sessionId} swap rejected: invalid token`);
-        return unauthenticatedResponse("invalid_token");
-      }
-      if (fresh.userId !== session.userId) {
-        console.warn(
-          `[mcp] session=${sessionId} swap REJECTED: ` +
-            `user mismatch (session=${session.userId} bearer=${fresh.userId})`,
-        );
-        return unauthenticatedResponse(
-          "invalid_token",
-          "Bearer does not belong to this session",
-        );
-      }
-      console.log(
-        `[mcp] session=${sessionId} token rotated user=${session.userId}`,
-      );
-      session.apiKey = apiKey;
-      session.client.setApiKey(apiKey);
-    }
-
-    // Reset the per-request 401 latch before handing off to the transport.
-    session.unauthorized = false;
-
-    const response = await session.transport.handleRequest(raw);
-
-    // If a tool call 401'd against harmony-api, the api-client tripped the
-    // unauthorized flag. Return HTTP 401 + WWW-Authenticate so the client
-    // refreshes — instead of burying the auth failure inside a JSON-RPC
-    // error envelope the client can't act on.
-    //
-    // Do NOT evict the session — per MCP spec, the session ID is
-    // independent of auth state. The next request arrives with a fresh
-    // bearer, the hot-swap above installs it, and the session continues.
-    if (session.unauthorized) {
-      console.log(`[mcp] session=${sessionId} api 401 → refresh challenge`);
-      return unauthenticatedResponse(
-        "invalid_token",
-        "Access token rejected by harmony-api",
-      );
-    }
-
-    return response;
+  // 2. POST is the whole protocol here — see methodNotAllowed().
+  if (raw.method === "GET") {
+    return methodNotAllowed(
+      "Method Not Allowed: this endpoint does not offer an SSE stream",
+    );
   }
-
-  // 3. No session id — only `initialize` is allowed; everything else is 400.
-  if (method !== "POST") {
-    // GET/DELETE without a session id are nonsense.
-    return sessionRequiredResponse();
+  if (raw.method === "DELETE") {
+    return methodNotAllowed(
+      "Method Not Allowed: stateless endpoint has no session to terminate",
+    );
   }
-
-  const body = await peekBody(raw);
-  if (!body || !isInitializeRequest(body)) {
-    return sessionRequiredResponse();
+  if (raw.method !== "POST") {
+    return methodNotAllowed(`Method Not Allowed: ${raw.method}`);
   }
 
-  // 4. Initialize path — validate token, create session, hand off.
+  // 3. Validate the bearer on EVERY request. Stateless means there is no session
+  //    to inherit trust from — the token is the only credential, and the userId
+  //    it resolves to is what selects the context below. Cached for 30s, so a
+  //    burst of parallel tool calls costs one lookup.
   const keyInfo = await validateToken(apiKey);
   if (!keyInfo) {
     return unauthenticatedResponse("invalid_token");
   }
-  if (keyInfo.source === "api_key" && !keyInfo.workspaceId) {
-    keyInfo.workspaceId = await resolveWorkspaceForLegacyKey(apiKey);
+
+  const body = await peekBody(raw);
+  const isInit = body !== undefined && isInitializeRequest(body);
+
+  // 4. A session id we could not have issued → 404, so the client re-handshakes
+  //    once and we learn who it is. Skipped for `initialize` itself, which is
+  //    already the handshake (and shouldn't be carrying one).
+  const sessionId = c.req.header("Mcp-Session-Id");
+  if (sessionId && !isInit) {
+    console.log(`[mcp] session=${sessionId} presented → 404 re-init`);
+    return sessionNotFound(sessionId);
+  }
+
+  const ctx = await resolveUserContext(apiKey, keyInfo);
+
+  // Remember who is calling. Only `initialize` carries clientInfo, so this is
+  // the single chance to learn the identity auto-sessions attribute work to.
+  if (isInit) {
+    const info = extractClientInfo(body);
+    if (info) rememberClientIdentity(ctx.contextKey, info);
   }
 
-  const session = createSession(apiKey, keyInfo);
-  await session.server.connect(session.transport);
+  // 5. Everything this request runs against — its own client bound to its own
+  //    bearer, and a snapshot of the context it must not see change mid-flight.
+  const { deps, authState } = buildRequestScope(ctx, apiKey, keyInfo);
+
+  // 6. Fresh Server + transport per request. Mandatory in stateless mode: the
+  //    SDK throws if a stateless transport handles a second request, because
+  //    JSON-RPC ids from unrelated clients would collide in its stream map.
+  const server = new Server(
+    { name: "harmony-mcp-remote", version: "1.0.0" },
+    { capabilities: { tools: {}, resources: {} } },
+  );
+  registerHandlers(server, deps);
 
-  const response = await session.transport.handleRequest(raw, {
-    parsedBody: body,
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+    enableJsonResponse: true,
   });
 
-  // Edge case: token revoked mid-handshake. Evict the half-built session.
-  if (session.unauthorized) {
-    if (session.transport.sessionId) evictSession(session.transport.sessionId);
-    return unauthenticatedResponse("invalid_token");
-  }
+  try {
+    await server.connect(transport);
+    // `enableJsonResponse` resolves with a fully-materialised JSON Response once
+    // every request in the body has been answered — nothing is still streaming
+    // when this returns, so the teardown below is safe.
+    const response = await transport.handleRequest(
+      raw,
+      body !== undefined ? { parsedBody: body } : undefined,
+    );
+
+    // A tool call that 401'd against harmony-api tripped this request's own
+    // latch (the client is not shared, so it can only be ours). Answer with
+    // HTTP 401 + WWW-Authenticate so the client refreshes, instead of burying
+    // the auth failure in a JSON-RPC envelope it can't act on.
+    if (authState.unauthorized) {
+      console.log(`[mcp] user=${ctx.userId} api 401 → refresh challenge`);
+      return unauthenticatedResponse(
+        "invalid_token",
+        "Access token rejected by harmony-api",
+      );
+    }
 
-  return response;
+    return response;
+  } finally {
+    // Closes the transport too (Protocol.close forwards). The user's context,
+    // sweep client, and auto-session scope survive — only the request-scoped
+    // protocol machinery and its client are torn down.
+    await server.close().catch(() => {});
+  }
 };
 
 app.all("/mcp", handleMcpRequest);
@@ -586,7 +933,10 @@ app.all("/", handleMcpRequest);
 // `serve()` call uses below. Tests construct synthetic Requests and assert on
 // the Response without binding to a real port.
 export const fetchHandler = app.fetch;
-export { sessions as _sessionsForTests };
+export {
+  userContexts as _userContextsForTests,
+  clientIdentities as _clientIdentitiesForTests,
+};
 
 // ---------------------------------------------------------------------------
 // Start server (skipped when imported as a module — e.g., from tests)