@cloudgrid-io/mcp 0.21.4 → 0.21.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.21.4",
+  "version": "0.21.6",
   "description": "MCP access to CloudGrid — the live runtime environment where the user's apps run WITH the infrastructure they need out of the box: managed MongoDB, Redis (cache/queues/pub-sub), a pgvector store, persistent disk, and built-in AI with no API keys, in any language or stack, no Docker or Kubernetes to manage. Brainstorm, build, plug, and improve apps, games, dashboards, and tools; instant single-page publishes and full runtime-app deploys with a live URL — for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server.",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "start:web": "node src/web.js",
     "smoke": "node test/smoke.mjs",
     "test:plug-wire": "node test/plug-wire.test.mjs",
+    "test:plug-grid-derive": "node test/plug-grid-derive.test.mjs",
     "test:session-log": "node test/session-logger.test.mjs",
     "test:error-reporting": "node test/error-reporting.test.mjs",
     "test:source": "node test/source-fetch.test.mjs",
@@ -65,7 +66,9 @@
     "test:pull-grid": "node test/pull-grid-param.test.mjs",
     "test:pull-output-schema": "node test/pull-output-schema.test.mjs",
     "test:web-identity": "node --test test/web-identity.test.mjs",
-    "test:web-auth-integration": "node --test test/web-auth-integration.test.mjs"
+    "test:web-auth-integration": "node --test test/web-auth-integration.test.mjs",
+    "test:web-restart-recovery": "node --test test/web-restart-recovery.test.mjs",
+    "test:web-capabilities-log": "node --test test/web-capabilities-log.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",

package/src/tools/deploy.js

@@ -848,10 +848,8 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id, grid } =
     let msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
     // The API's "Set the X-CloudGrid-Grid header" error is unactionable for an
     // MCP client (no client can set HTTP headers on a tool call). Rewrite it to
-    // name the tool parameter the caller CAN set (#247).
-    if (res.status === 400 && /X-CloudGrid-Grid/i.test(msg)) {
-      msg = "You belong to more than one grid. Pass the `grid` parameter to specify which grid to use.";
-    }
+    // name the tool parameter the caller CAN set (#247; class-level since #296).
+    if (res.status === 400) msg = rewriteGridHeaderError(msg);
     throw new Error(`Pull failed (HTTP ${res.status}): ${msg}`);
   }
 
@@ -968,7 +966,10 @@ export async function runCollab(ctx, { entity_id, grid } = {}) {
     if (res.status === 400 && code === "NOT_A_RUNTIME") {
       throw new Error(data?.error?.message || `'${target}' is an Inspiration, not an app or agent — it has no collaborators. Fork it with grid_pickup instead.`);
     }
-    const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
+    let msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
+    // Never surface the raw "Set the X-CloudGrid-Grid header" text — name the
+    // `grid` parameter instead (#296 class-level fix; see rewriteGridHeaderError).
+    if (res.status === 400) msg = rewriteGridHeaderError(msg);
     throw new Error(`Collab failed (HTTP ${res.status}): ${msg}`);
   }
 
@@ -1442,10 +1443,38 @@ export const REPORT_OFFER =
   "then call grid_report with the error + the failed request context. " +
   "Do NOT report without an explicit yes, and do NOT include the full conversation unless the user explicitly agrees.";
 
+// The API's "Set the X-CloudGrid-Grid header" 400 (code GRID_HEADER_REQUIRED) is
+// STRUCTURALLY unactionable for an MCP client: no client can set an HTTP header
+// on a tool call, so a model reading it starts guessing (observed live, #296).
+// Rewrite it to name the tool PARAMETER the caller CAN set. `param` is the grid-
+// carrying parameter on the calling tool (`grid` on plug/pull/collab/visibility;
+// `into_org_slug` on pickup). First added inline on the pull path for #247; this
+// is the class-level version applied at every authed write path.
+//
+// A message is a grid-header error when the code says so OR the text names the
+// header — matching both survives an API message reword. Anything else passes
+// through unchanged. The rewritten text never contains the words "header" or
+// "X-CloudGrid-Grid", nor the internal code.
+export function isGridHeaderError(code, msg) {
+  return code === "GRID_HEADER_REQUIRED" || /X-CloudGrid-Grid/i.test(msg || "");
+}
+export function rewriteGridHeaderError(msg, param = "grid") {
+  if (!isGridHeaderError(null, msg)) return msg;
+  return `You belong to more than one grid. Pass the \`${param}\` parameter to specify which grid to use.`;
+}
+
 // Map friendly plug error statuses to actionable messages (spec v2 §3.3).
 // Appends errorGuidance() for known codes; unknown codes pass through as the
 // bare `base` line, unchanged.
 function plugErrorMessage(status, code, msg, ctxFlags = {}) {
+  // A GRID_HEADER_REQUIRED (or any 400 naming the header) is unactionable —
+  // rewrite it to name the `grid` PARAMETER and DROP the internal code from the
+  // prefix (the code string itself contains "HEADER"). Class-level fix (#296);
+  // mirrors the pull-path rewrite (#247). Part A derives the grid on an edit so
+  // this normally never fires there; it still guards multi-grid CREATES.
+  if (status === 400 && isGridHeaderError(code, msg)) {
+    return `Plug failed (HTTP 400): ${rewriteGridHeaderError(msg)}`;
+  }
   const base = `Plug failed (HTTP ${status}${code ? ` ${code}` : ""}): ${msg}`;
   const guidance = errorGuidance({ status, code, ...ctxFlags });
   return guidance ? `${base} — ${guidance}` : base;
@@ -1743,6 +1772,17 @@ export async function runPlug(ctx, input, deps = {}) {
     // entity's grid, so pass `grid` here too when the target lives outside the
     // active grid.
     orgSlug = grid || (await ctx.getActiveGrid());
+    // #296: an EDIT's destination is NOT ambiguous — the entity already lives in
+    // exactly one grid. When neither an explicit `grid` nor active-grid session
+    // state resolves one (the common hosted case, where active-grid is often
+    // unset), derive the home grid from the target entity itself so the write
+    // never depends on session state the API would otherwise reject for
+    // (GRID_HEADER_REQUIRED). Best-effort metadata resolve via the pickup
+    // contract (no claim); a null result simply falls back to today's behaviour.
+    if (!orgSlug && isEdit && targetEntityId) {
+      const resolved = await resolveEntityViaPickup(ctx, { target: targetEntityId });
+      if (resolved?.grid) orgSlug = resolved.grid;
+    }
     // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak.
     if (orgSlug) {
       headers["X-CloudGrid-Grid"] = orgSlug;
@@ -2134,7 +2174,7 @@ export async function runPlug(ctx, input, deps = {}) {
   return { text: lines.join("\n"), structured };
 }
 
-async function authedApiCall(ctx, { method, pathName, body, verb }) {
+async function authedApiCall(ctx, { method, pathName, body, verb, gridParam = "grid" }) {
   const token = await ctx.getToken();
   if (!token) {
     throw new Error(`${verb} requires sign-in. Run grid_login first.`);
@@ -2167,7 +2207,13 @@ async function authedApiCall(ctx, { method, pathName, body, verb }) {
   if (!res.ok) {
     const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
     const codeStr = data?.error?.code || null;
-    const err = new Error(`${verb} failed (HTTP ${res.status}${codeStr ? ` ${codeStr}` : ""}): ${msg}`);
+    // A GRID_HEADER_REQUIRED is unactionable — name the grid-carrying parameter
+    // (into_org_slug for pickup) and drop the internal code from the prefix (it
+    // contains "HEADER"). #296 class-level fix; see rewriteGridHeaderError.
+    const errText = isGridHeaderError(codeStr, msg)
+      ? `${verb} failed (HTTP ${res.status}): ${rewriteGridHeaderError(msg, gridParam)}`
+      : `${verb} failed (HTTP ${res.status}${codeStr ? ` ${codeStr}` : ""}): ${msg}`;
+    const err = new Error(errText);
     // Expose the structured status/code so callers can branch (e.g. runPickup's
     // NOT_A_RUNTIME → inspiration-route fallback). Additive: existing callers
     // only read `.message`.
@@ -2194,6 +2240,9 @@ export async function runPickup(ctx, { id, into_org_slug, name, source_version_i
       ...(source_version_id ? { source_version_id } : {}),
     },
     verb: "Pickup",
+    // A fork's destination is chosen by the caller via into_org_slug, so a
+    // GRID_HEADER_REQUIRED must point there, not at a non-existent `grid` param.
+    gridParam: "into_org_slug",
   });
   const gridSlug = data?.grid_slug ?? data?.org?.slug ?? null;
   const lines = [
@@ -2430,8 +2479,11 @@ export async function runVisibility(ctx, { target, visibility, inside, outside,
     if (!canFallback) break;
   }
 
-  const msg = last?.data?.error?.message || last?.raw || `HTTP ${last?.res?.status}`;
+  let msg = last?.data?.error?.message || last?.raw || `HTTP ${last?.res?.status}`;
   const hint = last?.data?.error?.details?.[0]?.hint;
+  // Never surface the raw header text — name the `grid` parameter (grid_visibility
+  // accepts one via `org`, exposed to callers as the grid). #296 class-level fix.
+  if (last?.res?.status === 400) msg = rewriteGridHeaderError(msg);
   throw new Error(`Visibility change failed (HTTP ${last?.res?.status}): ${msg}${hint ? ` ${hint}` : ""}`);
 }
 

package/src/tools/register.js

@@ -47,6 +47,33 @@ export function buildCreateProjectArgs({ kind, name, type, needs, dir, grid, org
   return args;
 }
 
+// ── Sign-in ask (#298) ──────────────────────────────────────────────────────
+// Until a rendered login card is possible (blocked on #297's answer + the
+// directory submission), this text IS the whole login experience on every
+// client, so it is written to be RELAYED nearly verbatim. The user-facing part
+// comes first — a short question, then the two evenly-weighted options (guest is
+// a real choice, not a fallback). The model-directed steps (which tool to call,
+// do not choose, wait) are quarantined in a trailing (assistant: …) line so the
+// model does not read internal directions aloud. §23 voice: plain, no emoji, no
+// exclamation; say "plug" and "grid". The sign-in URL itself lands on its own
+// line later, from grid_login. No structural change — every caller still returns
+// { needs_auth: true }.
+const AUTH_ASK_SIGNED_OUT =
+  "How would you like to plug this?\n" +
+  "  - Sign in to your grid — it stays in your CloudGrid account.\n" +
+  "  - As a guest — live now at a link that expires in 7 days unless you claim it.\n\n" +
+  "(assistant: offer both options and let the user choose — do not choose for them. " +
+  "To sign in, call grid_login; as a guest, re-call grid_plug with anon: true. " +
+  "Stop and wait for their answer.)";
+const authAskSignedIn = (who) =>
+  `You are signed in${who}.\n\n` +
+  "How would you like to plug this?\n" +
+  "  - To your grid — it stays in your CloudGrid account.\n" +
+  "  - As a guest — live now at a link that expires in 7 days unless you claim it.\n\n" +
+  "(assistant: offer both options and let the user choose — do not choose for them. " +
+  "For their grid, re-call grid_plug; as a guest, re-call grid_plug with anon: true. " +
+  "Stop and wait for their answer.)";
+
 // ── Registration ───────────────────────────────────────────────────────────────
 // Registers the tools onto `server`. ctx.edition decides whether the CLI-wrapping
 // tools are included (they need a local machine).
@@ -515,31 +542,19 @@ export function registerTools(server, ctx) {
               const claims = decodeJwtAuth(token);
               const who = claims.email ? ` as ${claims.email}` : "";
               return okResult({
-                text:
-                  `You are signed in${who}. The user has not explicitly chosen anonymous publishing. Ask the user which they want — do not choose for them:\n` +
-                  `  1. Publish to your grid (re-call grid_plug without anon: true).\n` +
-                  `  2. Publish anonymously — a guest link that expires in 7 days unless claimed (re-call grid_plug with anon: true).\n` +
-                  `Relay this question to the user and STOP until they answer.`,
+                text: authAskSignedIn(who),
                 structured: { needs_auth: true },
               });
             }
             return okResult({
-              text:
-                "This is a new publish and the user is not signed in. Ask the user which they want — do not choose for them:\n" +
-                "  1. Sign in and plug it to their grid — run grid_login (opens the browser), then re-call grid_plug.\n" +
-                "  2. Plug it as a guest — live immediately at a guest link that expires in 7 days unless claimed (re-call grid_plug with anon: true).\n" +
-                "Relay this question to the user and STOP until they answer.",
+              text: AUTH_ASK_SIGNED_OUT,
               structured: { needs_auth: true },
             });
           }
           if (!token && input?.anon !== true) {
             if (ctx.state) ctx.state.authChoiceOffered = true;
             return okResult({
-              text:
-                "This is a new publish and the user is not signed in. Ask the user which they want — do not choose for them:\n" +
-                "  1. Sign in and plug it to their grid — run grid_login (opens the browser), then re-call grid_plug.\n" +
-                "  2. Plug it as a guest — live immediately at a guest link that expires in 7 days unless claimed (re-call grid_plug with anon: true).\n" +
-                "Relay this question to the user and STOP until they answer.",
+              text: AUTH_ASK_SIGNED_OUT,
               structured: { needs_auth: true },
             });
           }
@@ -660,8 +675,11 @@ export function registerTools(server, ctx) {
       if (ctx.canOpenBrowser) tryOpenBrowser(url);
       return {
         content: [{ type: "text", text:
-          `To sign in, open this URL in your browser and finish with Google:\n${url}\n\n` +
-          `After you complete it, run grid_login_status to finish signing in.`,
+          // #298: the sign-in link on its own line, unadorned, so every client
+          // linkifies it and the eye lands on it; the model-directed follow-up is
+          // quarantined in the trailing (assistant: …) line.
+          `Open this link to sign in, then finish in your browser:\n\n${url}\n\n` +
+          `(assistant: after they complete it, call grid_login_status to finish.)`,
         }],
         structuredContent: { login_url: url },
       };

package/src/web.js

@@ -22,7 +22,11 @@ import { randomUUID } from "node:crypto";
 import express from "express";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import {
+  isInitializeRequest,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  LATEST_PROTOCOL_VERSION,
+} from "@modelcontextprotocol/sdk/types.js";
 import { registerTools } from "./tools.js";
 import { mountOAuth, bearerChallenge } from "./oauth.js";
 import { mountLanding } from "./landing.js";
@@ -53,10 +57,25 @@ function bearerOf(req) {
   return h && /^Bearer\s+\S+/i.test(h) ? h.replace(/^Bearer\s+/i, "") : null;
 }
 
+// Reduce an object to its KEY SHAPE — key names mapped to the TYPE of each value,
+// recursively — never the values themselves. Used to log the client's advertised
+// MCP capabilities at initialize (#297) while guaranteeing BY CONSTRUCTION that
+// no value ever leaves the process: only key names and JS type names are emitted,
+// so no token, header, tool argument, or user content can appear even if the
+// object carried one. Depth- and breadth-capped so a malformed or huge object
+// cannot blow the stack or flood the log.
+function keyShape(value, depth = 0) {
+  if (value === null || typeof value !== "object" || depth >= 6) return typeof value;
+  if (Array.isArray(value)) return `array[${value.length}]`;
+  const out = {};
+  for (const k of Object.keys(value).slice(0, 64)) out[k] = keyShape(value[k], depth + 1);
+  return out;
+}
+
 // A web session: identity lives in memory for the session's lifetime only. The
 // session id doubles as the stable, opaque end-user id for the trusted-server cap.
-// The identity is built by the caller so the transport auth guard can consult it
-// (hasUsableCredential) before the session is wired up.
+// The identity carries the request's transport token; auth is enforced in-band by
+// the tool layer (needs_auth via grid_login / grid_plug), not by a transport gate.
 function makeWebContext(sessionId, identity) {
   return {
     edition: "web",
@@ -115,54 +134,15 @@ function captureRequestIdentity(sessionId, jwt) {
   }
 }
 
-app.post("/mcp", async (req, res) => {
-  const sessionId = req.headers["mcp-session-id"];
-  let transport = sessionId ? transports[sessionId] : undefined;
-  const jwt = bearerOf(req);
-
-  if (REQUIRE_AUTH && !jwt) {
-    sendAuthChallenge(res);
-    return;
-  }
-
-  if (transport) {
-    captureRequestIdentity(sessionId, jwt);
-    // An expired/invalid transport token with no valid explicit login means the
-    // session holds no usable credential — challenge so the client re-runs OAuth,
-    // rather than proceeding and degrading to an in-band copy-paste login link
-    // (#286). Consult the identity, not the raw Bearer: an explicit in-session
-    // login stays authoritative over an expired transport token (#279/#280).
-    const ctx = sessionContexts[sessionId];
-    if (REQUIRE_AUTH && ctx && !ctx.identity.hasUsableCredential()) {
-      sendAuthChallenge(res);
-      return;
-    }
-    await transport.handleRequest(req, res, req.body);
-    return;
-  }
-
-  if (sessionId || !isInitializeRequest(req.body)) {
-    res.status(400).json({
-      jsonrpc: "2.0",
-      error: { code: -32000, message: "No valid session. Send an initialize request first." },
-      id: null,
-    });
-    return;
-  }
-
-  // New session: fresh server + per-session identity context. Generate the session
-  // id up front so it is also the trusted-server end-user id. (Distinct name from
-  // the incoming `sessionId` header above.)
-  const newSessionId = randomUUID();
+// Build a fresh MCP session — server + transport + per-session identity context —
+// keyed by `sessionId`. `sessionId` is also the trusted-server end-user id and,
+// for a rehydrated (restart-evicted) session, the id the client keeps presenting.
+// Identity derives ONLY from the credential passed here (`jwt`), never from
+// anything remembered about the id: a session id is not proof of identity.
+async function buildSession(sessionId, jwt) {
   const identity = createWebIdentity({ initialTransportToken: jwt });
-  // A brand-new session has no explicit login yet, so the transport Bearer is the
-  // only possible credential — challenge if it is expired or undecodable (#286).
-  if (REQUIRE_AUTH && !identity.hasUsableCredential()) {
-    sendAuthChallenge(res);
-    return;
-  }
-  transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: () => newSessionId,
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => sessionId,
     onsessioninitialized: (sid) => {
       transports[sid] = transport;
     },
@@ -177,17 +157,17 @@ app.post("/mcp", async (req, res) => {
     }
   };
   const server = new McpServer({ name: "cloudgrid-mcp-web", version }, { instructions: INSTRUCTIONS_WEB });
-  const webCtx = makeWebContext(newSessionId, identity);
-  sessionContexts[newSessionId] = webCtx;
+  const webCtx = makeWebContext(sessionId, identity);
+  sessionContexts[sessionId] = webCtx;
   // QA session log for this MCP session (dark by default). Keyed by the session
   // id — the host connection boundary. No seed user_request here: current hosts
   // don't forward the first message. The model-as-courier path fills it instead —
   // grid_plug's user_request arg lifts the ask into the log (setUserRequest);
   // absent that, the log records the explicit not-provided line.
-  webCtx.sessionId = newSessionId;
+  webCtx.sessionId = sessionId;
   webCtx.logger = createSessionLogger({
     transport: "hosted",
-    sessionId: newSessionId,
+    sessionId,
     sink: createSink(process.env),
     ctx: webCtx,
   });
@@ -201,8 +181,160 @@ app.post("/mcp", async (req, res) => {
     } catch {
       webCtx.state.client = null;
     }
+    // #297: record the client's advertised MCP capabilities once per session, so
+    // we can settle whether Claude web ever advertises a UI extension (e.g.
+    // io.modelcontextprotocol/ui) — the plumbing a rendered login card would
+    // need — instead of guessing while the directory submission sits unanswered.
+    // Observation-only: only the capability KEY SHAPE (names + value types, never
+    // values — see keyShape) is logged, so no credential or user content can
+    // appear. Skip the synthetic rehydrate initialize so the signal stays clean.
+    // Wrapped so a logging failure can never affect the session (zero behaviour
+    // change if capabilities is absent or malformed).
+    try {
+      const client = server.server.getClientVersion() ?? null;
+      if (client?.name !== "cloudgrid-mcp-rehydrate") {
+        const caps = server.server.getClientCapabilities();
+        const shape = caps && typeof caps === "object" ? keyShape(caps) : null;
+        // eslint-disable-next-line no-console
+        console.error(
+          `cloudgrid-mcp: client-capabilities client=${client?.name ?? "unknown"} capabilities=${JSON.stringify(shape)}`,
+        );
+      }
+    } catch {
+      /* observation-only — never affects the session */
+    }
   };
   await server.connect(transport);
+  return { transport, identity };
+}
+
+// Drive an in-process MCP initialize so a freshly-built transport is usable
+// WITHOUT the client sending its own initialize. This is the restart-recovery
+// path: a client whose session was evicted by a pod restart keeps presenting the
+// same stale mcp-session-id on ordinary tool calls and never re-initializes on
+// its own (Claude web does not act on the transport's 400 — see #292). The SDK's
+// StreamableHTTPServerTransport rejects any non-initialize request until it has
+// seen an initialize ("Bad Request: Server not initialized"), so we feed it a
+// synthetic initialize here — adopting the stale id via sessionIdGenerator — then
+// serve the real request on the same session. Verified against the SDK: this sets
+// _initialized, adopts the session id, and fires onsessioninitialized so the
+// transport registers itself for reuse by the client's subsequent requests.
+async function primeSession(transport, req) {
+  const wst = transport._webStandardTransport;
+  if (!wst || typeof wst.handleRequest !== "function") {
+    throw new Error("cannot rehydrate session: transport internals unavailable");
+  }
+  const proposed = req.headers["mcp-protocol-version"];
+  const protocolVersion =
+    typeof proposed === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(proposed)
+      ? proposed
+      : LATEST_PROTOCOL_VERSION;
+  const initBody = {
+    jsonrpc: "2.0",
+    id: "cg-rehydrate-init",
+    method: "initialize",
+    params: {
+      protocolVersion,
+      capabilities: {},
+      clientInfo: { name: "cloudgrid-mcp-rehydrate", version },
+    },
+  };
+  const initReq = new Request(`${PUBLIC_BASE}/mcp`, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+  });
+  const initRes = await wst.handleRequest(initReq, { parsedBody: initBody });
+  // Drain the synthetic initialize's SSE response so its stream closes and no
+  // keep-alive timer leaks. The initialize result itself is discarded — the
+  // client never sees it; it only ever sees the response to its real request.
+  try { await initRes.text(); } catch { /* the init result is discarded either way */ }
+}
+
+app.post("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"];
+  let transport = sessionId ? transports[sessionId] : undefined;
+  const jwt = bearerOf(req);
+
+  if (REQUIRE_AUTH && !jwt) {
+    sendAuthChallenge(res);
+    return;
+  }
+
+  if (transport) {
+    // Capture the request's transport token into the session identity — #279: an
+    // explicit in-session login stays authoritative over an expired transport
+    // token. Do NOT gate on expiry here. #288 added a transport-level 401 on an
+    // expired/invalid Bearer (the "#286 challenge"); it shipped in 0.21.3/0.21.4,
+    // was pulled from production (manifests re-pinned to 0.21.2) hours later, and
+    // #286 is closed not-planned. Auth on this connector is IN-BAND via grid_login
+    // / grid_plug (2026-08-23 founder decision), so a transport 401 on expiry is
+    // wrong by design — it bricks the client with grid_login behind the same 401.
+    // An expired-but-present Bearer must reach the tool layer, where the needs_auth
+    // ask is the recovery path. The only auth gate is the missing-Bearer guard at
+    // the top of this handler (the deployed v0.21.2 posture).
+    captureRequestIdentity(sessionId, jwt);
+    await transport.handleRequest(req, res, req.body);
+    return;
+  }
+
+  const isInit = isInitializeRequest(req.body);
+
+  // A brand-new connection with no session id that is NOT an initialize is a real
+  // protocol error — there is nothing to recover.
+  if (!sessionId && !isInit) {
+    res.status(400).json({
+      jsonrpc: "2.0",
+      error: { code: -32000, message: "No valid session. Send an initialize request first." },
+      id: null,
+    });
+    return;
+  }
+
+  if (isInit) {
+    // A genuine new session — mint a fresh id. The only auth gate is the top-of-
+    // handler missing-Bearer guard (the deployed v0.21.2 posture); the #288
+    // expired-Bearer transport 401 is reverted (see the transport-present block
+    // above), so an expired-but-present Bearer proceeds to the tool layer where
+    // the in-band needs_auth ask lives, rather than being challenged.
+    const newSessionId = randomUUID();
+    ({ transport } = await buildSession(newSessionId, jwt));
+    await transport.handleRequest(req, res, req.body);
+    return;
+  }
+
+  // A stale session id the process no longer knows — a non-initialize call whose
+  // session was evicted by a pod restart (#292). Rebuild ON THE SAME id the client
+  // keeps presenting, so it recovers without reconnecting. Identity comes ONLY from
+  // this request's Bearer; the stale id carries no remembered identity, and a
+  // rebuilt session legitimately loses the prior in-memory explicit-login override
+  // — degrading to a fresh grid_login, never silently reusing a login (#279/#280).
+  //
+  // No auth gate beyond the top-of-handler missing-Bearer guard (the deployed
+  // v0.21.2 posture): auth on the connected edge is IN-BAND via grid_login /
+  // grid_plug (2026-08-23 founder decision), so an expired-but-present Bearer — a
+  // connected session after a restart — must rebuild and reach the tool layer where
+  // the needs_auth ask is the recovery path, NOT be challenged with grid_login
+  // stuck behind the same 401 (the #286 brick, on the rebuild path). Gating on
+  // expiry (hasUsableCredential) here is exactly what #288 got wrong and was pulled
+  // from production for.
+  ({ transport } = await buildSession(sessionId, jwt));
+  // Rehydrate the evicted session. If priming fails (e.g. an SDK internal moved
+  // out from under us), tear the half-built session down and fall back to the
+  // original 400 rather than leaking a broken session or hanging the request —
+  // a re-initialize still recovers the client.
+  try {
+    await primeSession(transport, req);
+  } catch {
+    try { await transport.close(); } catch { /* best effort */ }
+    delete transports[sessionId];
+    delete sessionContexts[sessionId];
+    res.status(400).json({
+      jsonrpc: "2.0",
+      error: { code: -32000, message: "No valid session. Send an initialize request first." },
+      id: null,
+    });
+    return;
+  }
   await transport.handleRequest(req, res, req.body);
 });