@gethelio/proxy 0.11.0 → 0.12.0

package/dist/cli.js

@@ -39,10 +39,25 @@ function parseDuration(duration) {
   }
   return value * multiplier;
 }
+var RESERVED_TRANSPORT_HEADERS = /* @__PURE__ */ new Set([
+  "mcp-session-id",
+  "mcp-protocol-version",
+  "content-type",
+  "content-length",
+  "host",
+  // Modern (2026-07-28) transport headers Helio owns on the wire for every
+  // Streamable HTTP POST it sends upstream — relayed client traffic and
+  // proxy-initiated requests (era probe, revalidation) alike — see
+  // upstream-session-manager.ts and streamable-http-forwarder.ts.
+  "mcp-method",
+  "mcp-name"
+]);
 var transportSchema = z.enum(["streamable-http", "sse", "stdio"]);
+var protocolVersionSchema = z.enum(["auto", "2025-06-18", "2026-07-28"]);
 var upstreamSchema = z.object({
   url: z.string(),
   transport: transportSchema.default("streamable-http"),
+  protocol_version: protocolVersionSchema.default("auto"),
   command: z.string().optional(),
   args: z.array(z.string()).optional(),
   connect_timeout: durationSchema.default("10s"),
@@ -53,6 +68,13 @@ var upstreamSchema = z.object({
   message: '"command" is required when transport is "stdio"',
   path: ["command"]
 }).superRefine((data, ctx) => {
+  if (data.protocol_version === "2026-07-28" && data.transport !== "streamable-http") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["protocol_version"],
+      message: data.transport === "stdio" ? 'protocol_version "2026-07-28" requires transport "streamable-http" \u2014 stdio modern-era support is tracked in #256.' : 'protocol_version "2026-07-28" requires transport "streamable-http" \u2014 the SSE upstream transport is the deprecated legacy transport.'
+    });
+  }
   for (const [index, header] of data.forward_headers.entries()) {
     if (!header.toLowerCase().startsWith("x-")) {
       ctx.addIssue({
@@ -62,15 +84,8 @@ var upstreamSchema = z.object({
       });
     }
   }
-  const reserved = /* @__PURE__ */ new Set([
-    "mcp-session-id",
-    "mcp-protocol-version",
-    "content-type",
-    "content-length",
-    "host"
-  ]);
   for (const name of Object.keys(data.headers)) {
-    if (reserved.has(name.toLowerCase())) {
+    if (RESERVED_TRANSPORT_HEADERS.has(name.toLowerCase())) {
       ctx.addIssue({
         code: "custom",
         path: ["headers", name],
@@ -81,8 +96,63 @@ var upstreamSchema = z.object({
 });
 var listenSchema = z.object({
   port: z.number().int().min(1).max(65535).default(3e3),
-  host: z.string().default("127.0.0.1")
-}).strict();
+  host: z.string().default("127.0.0.1"),
+  /**
+   * Origin allowlist for the MCP transports (issue #213). Requests to /mcp
+   * or /sse carrying an Origin header not in this list are refused with 403.
+   * Empty (the default) means every Origin is refused — MCP clients are
+   * non-browser processes and never send one. This is NOT CORS support: the
+   * proxy emits no CORS response headers, so a browser still cannot read
+   * responses. The list exists for deployments where a fronting proxy or
+   * embedding host injects an Origin the operator needs to name.
+   */
+  allowed_origins: z.array(z.string().min(1)).default([])
+}).strict().superRefine((data, ctx) => {
+  for (const [index, entry] of data.allowed_origins.entries()) {
+    if (entry === "*") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["allowed_origins", index],
+        message: "listen.allowed_origins does not support wildcards \u2014 list each origin exactly."
+      });
+      continue;
+    }
+    if (entry === "null") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["allowed_origins", index],
+        message: 'The literal "null" cannot be allowlisted: it is the opaque origin sent by sandboxed frames, data: documents, and file:// pages, so allowing it would admit all of them.'
+      });
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = new URL(entry);
+    } catch {
+      ctx.addIssue({
+        code: "custom",
+        path: ["allowed_origins", index],
+        message: `"${entry}" is not a serialized origin. Use scheme://host[:port], e.g. "http://localhost:5173".`
+      });
+      continue;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["allowed_origins", index],
+        message: `"${entry}" is not an http(s) origin. Allowlist entries must be serialized http(s) origins, e.g. "http://localhost:5173".`
+      });
+      continue;
+    }
+    if (parsed.origin !== entry) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["allowed_origins", index],
+        message: `"${entry}" is not in serialized origin form and would never match a browser-sent Origin \u2014 did you mean "${parsed.origin}"?`
+      });
+    }
+  }
+});
 function isLoopbackHost(host) {
   return host === "127.0.0.1" || host === "localhost" || host === "::1";
 }
@@ -97,6 +167,56 @@ var dashboardSchema = z.object({
   allow_open_mode: z.boolean().default(false),
   sse_heartbeat_interval: durationSchema.default("30s")
 }).strict();
+var sessionHeaderSourceSchema = z.object({
+  source: z.literal("header"),
+  /** Lowercased on parse — HTTP header names are case-insensitive. */
+  name: z.string().min(1).default("x-helio-session-id").transform((name) => name.toLowerCase())
+}).strict();
+var sessionMetaSourceSchema = z.object({
+  source: z.literal("meta")
+}).strict();
+var sessionLegacyHeaderSourceSchema = z.object({
+  source: z.literal("legacy_header")
+}).strict();
+var sessionIdentitySourceSchema = z.discriminatedUnion("source", [
+  sessionHeaderSourceSchema,
+  sessionMetaSourceSchema,
+  sessionLegacyHeaderSourceSchema
+]);
+var sessionSchema = z.object({
+  /** Ordered identity sources; the first source that yields a value wins. */
+  identity: z.array(sessionIdentitySourceSchema).min(1, {
+    message: "session.identity cannot be empty \u2014 an empty chain would leave every request unresolved. Omit the section to use the defaults, or list at least one source."
+  }).default([{ source: "header", name: "x-helio-session-id" }, { source: "legacy_header" }]),
+  on_unresolved: z.enum(["deny", "anonymous"]).default("deny")
+}).strict().superRefine((session, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, entry] of session.identity.entries()) {
+    if (entry.source !== "header") continue;
+    if (!entry.name.startsWith("x-")) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["identity", index, "name"],
+        message: 'Session identity header names must start with "x-" (for example "x-helio-session-id")'
+      });
+    }
+    if (RESERVED_TRANSPORT_HEADERS.has(entry.name)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["identity", index, "name"],
+        message: `session.identity must not read reserved transport header "${entry.name}" \u2014 the proxy owns it on the wire. Use source: legacy_header for Mcp-Session-Id, or a custom x- header.`
+      });
+    }
+    if (seen.has(entry.name)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["identity", index, "name"],
+        message: `Duplicate session identity header "${entry.name}" \u2014 the first entry always wins, so the duplicate is dead config. Remove it.`
+      });
+    }
+    seen.add(entry.name);
+  }
+});
 var inputConditionSchema = z.object({
   eq: z.unknown().optional(),
   neq: z.unknown().optional(),
@@ -195,6 +315,21 @@ var installSchema = z.object({
   default: z.enum(["allow", "deny"]).default("allow"),
   rules: z.array(installRuleSchema).default([])
 }).strict();
+var toolRevalidationSchema = z.object({
+  enabled: z.boolean().default(true),
+  interval: durationSchema.default("5m"),
+  // Default: `interval`, applied at compile time (undefined here means
+  // "same as interval" — see PoliciesConfig compilation).
+  max_advertised_ttl: durationSchema.optional()
+}).strict().superRefine((data, ctx) => {
+  if (parseDuration(data.interval) < 1e4) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["interval"],
+      message: "tool_revalidation.interval must be at least 10s"
+    });
+  }
+});
 var policiesSchema = z.object({
   default: z.enum(["allow", "deny"]).default("allow"),
   flag_destructive: z.enum(["log", "require_approval"]).optional(),
@@ -215,6 +350,13 @@ var policiesSchema = z.object({
    * don't need the field; undefined is treated as "block".
    */
   on_tool_drift: z.enum(["block", "require_approval", "log"]).optional(),
+  /**
+   * Proxy-scheduled `tools/list` revalidation and `ttlMs` clamping (issue
+   * #221). Optional; absent ⇒ compiled defaults (enabled: true, interval:
+   * "5m") in `CompiledPolicy`, except in literal `CompiledPolicy` fixtures,
+   * which treat an absent field as disabled — see `compilePolicies`.
+   */
+  tool_revalidation: toolRevalidationSchema.optional(),
   /**
    * Whether `helio start` should watch the config file for changes and
    * reconcile policy state on every save. Defaults to `true` when omitted.
@@ -349,6 +491,10 @@ var helioConfigBaseSchema = z.object({
   upstream: upstreamSchema,
   listen: listenSchema.prefault({}),
   environment: z.string().optional(),
+  // Session precedes policies deliberately: upstream/listen/environment say
+  // where and as-what Helio runs, session says who is calling, and
+  // policies/budgets then govern those calls (issue #218).
+  session: sessionSchema.prefault({}),
   policies: policiesSchema.prefault({}),
   // Budgets sit beside policies deliberately: they are the second half of the
   // governance declaration (policy decision → budget gate), not plumbing.
@@ -681,6 +827,9 @@ function diffReloadBoundary(previous, next) {
   if (!isDeepStrictEqual(previous.environment, next.environment)) {
     restartRequiredPaths.push("environment");
   }
+  if (!isDeepStrictEqual(previous.session, next.session)) {
+    restartRequiredPaths.push("session");
+  }
   if (!isDeepStrictEqual(previous.approval, next.approval)) {
     restartRequiredPaths.push("approval");
   }
@@ -790,11 +939,18 @@ var METADATA_OPERATORS = ["eq", "neq", "contains", "regex"];
 function compilePolicies(config) {
   const warnings = [];
   const rules = config.rules.map((rule, index) => compileRule(rule, index, warnings));
+  const rv = config.tool_revalidation;
+  const toolRevalidation = {
+    enabled: rv?.enabled ?? true,
+    intervalMs: parseDuration(rv?.interval ?? "5m"),
+    maxAdvertisedTtlMs: parseDuration(rv?.max_advertised_ttl ?? rv?.interval ?? "5m")
+  };
   const policy = {
     defaultAction: config.default,
     flagDestructive: config.flag_destructive,
     ...config.dry_run && { dryRun: true },
     ...config.on_tool_drift && { onToolDrift: config.on_tool_drift },
+    toolRevalidation,
     rules,
     ...config.install && { install: compileInstallPolicy(config.install) }
   };
@@ -1151,10 +1307,17 @@ var PARSE_ERROR = -32700;
 var INVALID_REQUEST = -32600;
 var INVALID_PARAMS = -32602;
 var INTERNAL_ERROR = -32603;
+var HEADER_MISMATCH = -32020;
 function makeJsonRpcError(id, code, message) {
   return {
     jsonrpc: "2.0",
-    id: id ?? null,
+    id,
+    error: { code, message }
+  };
+}
+function makeJsonRpcErrorWithoutId(code, message) {
+  return {
+    jsonrpc: "2.0",
     error: { code, message }
   };
 }
@@ -1223,6 +1386,79 @@ function parseJsonRpcRequest(body) {
   };
 }
 
+// src/mcp/session-resolver.ts
+var MAX_SESSION_ID_LENGTH = 256;
+var CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo";
+function compileSessionIdentity(config) {
+  const strategySummary = config.identity.map((entry) => entry.source === "header" ? `header "${entry.name}"` : entry.source).join(", ");
+  return {
+    sources: config.identity,
+    onUnresolved: config.on_unresolved,
+    strategySummary
+  };
+}
+var DEFAULT_SESSION_IDENTITY = compileSessionIdentity({
+  identity: [{ source: "header", name: "x-helio-session-id" }, { source: "legacy_header" }],
+  on_unresolved: "deny"
+});
+function paramsMeta(params) {
+  if (params === null || typeof params !== "object" || Array.isArray(params)) return void 0;
+  return params["_meta"];
+}
+var malformedValueWarned = false;
+function sanitizeCandidate(value, origin) {
+  if (value === void 0) return void 0;
+  if (value.trim() === "" || value.length > MAX_SESSION_ID_LENGTH) {
+    if (!malformedValueWarned) {
+      malformedValueWarned = true;
+      console.error(
+        `[helio] Warning: session identity value from ${origin} was skipped (empty or longer than ${String(MAX_SESSION_ID_LENGTH)} chars); continuing down the identity chain. Further skips will not be logged.`
+      );
+    }
+    return void 0;
+  }
+  return value;
+}
+function clientInfoId(meta) {
+  if (meta === null || typeof meta !== "object") return void 0;
+  const clientInfo = meta[CLIENT_INFO_META_KEY];
+  if (clientInfo === null || typeof clientInfo !== "object") return void 0;
+  const { name, version } = clientInfo;
+  if (typeof name !== "string" || name.trim() === "") return void 0;
+  return `clientinfo:${name}@${typeof version === "string" ? version : "unknown"}`;
+}
+function resolveSession(input, identity) {
+  for (const strategy of identity.sources) {
+    switch (strategy.source) {
+      case "header": {
+        const value = sanitizeCandidate(input.headers[strategy.name], `header "${strategy.name}"`);
+        if (value !== void 0) return { id: value, source: "header" };
+        break;
+      }
+      case "meta": {
+        const id = sanitizeCandidate(clientInfoId(input.meta), "meta clientInfo");
+        if (id !== void 0) return { id, source: "meta" };
+        break;
+      }
+      case "legacy_header": {
+        const value = sanitizeCandidate(input.transportSessionId, "legacy_header");
+        if (value !== void 0) return { id: value, source: "legacy_header" };
+        break;
+      }
+    }
+  }
+  if (input.transportMintedId !== void 0) {
+    return { id: input.transportMintedId, source: "transport" };
+  }
+  return void 0;
+}
+
+// src/transport/content-type.ts
+function isJsonContentType(header) {
+  const [essence = ""] = (header ?? "").split(";");
+  return essence.trim().toLowerCase() === "application/json";
+}
+
 // src/transport/forward-headers.ts
 function buildForwardHeaders(requestHeaders, allowlist) {
   const forwardHeaders = {};
@@ -1240,806 +1476,1419 @@ function buildForwardHeaders(requestHeaders, allowlist) {
   return Object.keys(forwardHeaders).length > 0 ? forwardHeaders : void 0;
 }
 
-// src/transport/response-normalizer.ts
-function isObject(value) {
-  return value !== null && typeof value === "object";
+// src/mcp/protocol-version.ts
+var HELIO_MCP_LEGACY_PROTOCOL_VERSION = "2025-06-18";
+var HELIO_MCP_MODERN_PROTOCOL_VERSION = "2026-07-28";
+function isModernProtocolClaim(rawValue) {
+  if (rawValue === void 0) return false;
+  const tokens = rawValue.split(",").map((token) => token.trim()).filter((token) => token.length > 0);
+  return tokens.length > 0 && tokens.every((token) => token === HELIO_MCP_MODERN_PROTOCOL_VERSION);
 }
-function isValidJsonRpcId(value) {
-  return value === null || typeof value === "string" || typeof value === "number";
+
+// src/upstream/standard-headers.ts
+var SENTINEL_PREFIX = "=?base64?";
+var SENTINEL_SUFFIX = "?=";
+var MCP_NAME_MAX_BYTES = 8192;
+var NAME_SOURCE_FIELD = /* @__PURE__ */ new Map([
+  ["tools/call", "name"],
+  ["prompts/get", "name"],
+  ["resources/read", "uri"]
+]);
+function needsSentinelEncoding(value) {
+  const hasUnsafeChar = /[^\t\x20-\x7E]/.test(value);
+  const hasEdgeWhitespace = /^[ \t]/.test(value) || /[ \t]$/.test(value);
+  const looksLikeSentinel = value.startsWith(SENTINEL_PREFIX) && value.endsWith(SENTINEL_SUFFIX);
+  return hasUnsafeChar || hasEdgeWhitespace || looksLikeSentinel;
+}
+function encodeSentinelValue(value) {
+  return `${SENTINEL_PREFIX}${Buffer.from(value, "utf8").toString("base64")}${SENTINEL_SUFFIX}`;
+}
+var SENTINEL_DECODE_PATTERN = /^=\?base64\?([A-Za-z0-9+/]*={0,2})\?=$/;
+function decodeSentinelValue(value) {
+  const match = SENTINEL_DECODE_PATTERN.exec(value);
+  return match ? Buffer.from(match[1] ?? "", "base64").toString("utf8") : value;
+}
+function nameBearingField(method) {
+  return NAME_SOURCE_FIELD.get(method);
+}
+function extractName(method, params) {
+  const field = NAME_SOURCE_FIELD.get(method);
+  if (!field || typeof params !== "object" || params === null || Array.isArray(params)) {
+    return void 0;
+  }
+  let source = params;
+  const maybeToJSON = params.toJSON;
+  if (typeof maybeToJSON === "function") {
+    try {
+      source = maybeToJSON.call(params, "params");
+    } catch {
+      return void 0;
+    }
+  }
+  if (typeof source !== "object" || source === null || Array.isArray(source)) {
+    return void 0;
+  }
+  if (!Object.prototype.propertyIsEnumerable.call(source, field)) {
+    return void 0;
+  }
+  const raw = source[field];
+  return typeof raw === "string" ? raw : void 0;
 }
-function getJsonRpcId(value) {
-  if (!isObject(value) || !Object.prototype.hasOwnProperty.call(value, "id")) return void 0;
-  const id = value["id"];
-  return isValidJsonRpcId(id) ? id : void 0;
+function isHeaderSafeMethod(method) {
+  return /^[\x21-\x7E]+$/.test(method);
 }
-function isValidJsonRpcError(value) {
-  if (!isObject(value)) return false;
-  return typeof value["code"] === "number" && typeof value["message"] === "string";
+function encodedNameValue(method, params) {
+  const name = extractName(method, params);
+  if (name === void 0) return void 0;
+  return needsSentinelEncoding(name) ? encodeSentinelValue(name) : name;
 }
-function isValidJsonRpcResponse(value) {
-  if (!isObject(value)) return false;
-  if (value["jsonrpc"] !== "2.0") return false;
-  if (Object.prototype.hasOwnProperty.call(value, "id") && !isValidJsonRpcId(value["id"])) {
-    return false;
+function buildStandardRequestHeaders(method, params) {
+  if (!isHeaderSafeMethod(method)) {
+    return {};
   }
-  const hasResult = Object.prototype.hasOwnProperty.call(value, "result");
-  const hasError = Object.prototype.hasOwnProperty.call(value, "error");
-  if (hasResult && hasError || !hasResult && !hasError) return false;
-  if (hasError && !isValidJsonRpcError(value["error"])) return false;
-  return true;
+  const headers = { "mcp-method": method };
+  const value = encodedNameValue(method, params);
+  if (value !== void 0 && Buffer.byteLength(value) <= MCP_NAME_MAX_BYTES) {
+    headers["mcp-name"] = value;
+  }
+  return headers;
 }
-function makeWrappedError(requestId, message, data) {
-  return {
-    jsonrpc: "2.0",
-    id: requestId ?? null,
-    error: {
-      code: INTERNAL_ERROR,
-      message,
-      data
+
+// src/upstream/merge-headers.ts
+function mergeUpstreamHeaders(base, forwarded, staticHeaders) {
+  const out = {};
+  const apply = (headers) => {
+    for (const [name, value] of Object.entries(headers)) {
+      out[name.toLowerCase()] = value;
     }
   };
+  apply(base);
+  apply(forwarded);
+  apply(staticHeaders);
+  return out;
 }
-function normalizeUpstreamOutcome(args) {
-  if (args.forwardingError) {
-    return {
-      httpStatus: 200,
-      wrapped: true,
-      body: makeWrappedError(args.requestId, "upstream forwarding failed", {
-        failure_class: "upstream_forward_error",
-        failure_reason: args.forwardingError.message
-      })
-    };
-  }
-  if (!args.upstreamResponse) {
-    return {
-      httpStatus: 200,
-      wrapped: true,
-      body: makeWrappedError(args.requestId, "upstream forwarding failed", {
-        failure_class: "upstream_forward_error",
-        failure_reason: "missing upstream response"
-      })
-    };
-  }
-  const upstream = args.upstreamResponse;
-  const upstreamContentType = upstream.headers["content-type"] ?? null;
-  if (!isValidJsonRpcResponse(upstream.body)) {
-    return {
-      httpStatus: 200,
-      wrapped: true,
-      body: makeWrappedError(args.requestId, "upstream returned invalid JSON-RPC response", {
-        failure_class: "upstream_invalid_jsonrpc",
-        upstream_http_status: upstream.status,
-        upstream_content_type: upstreamContentType,
-        upstream_body_type: typeof upstream.body
-      })
-    };
-  }
-  if (args.requestId !== void 0) {
-    const upstreamId = getJsonRpcId(upstream.body);
-    if (upstreamId === void 0) {
-      return {
-        httpStatus: 200,
-        wrapped: true,
-        body: makeWrappedError(args.requestId, "upstream returned invalid JSON-RPC response", {
-          failure_class: "upstream_invalid_jsonrpc",
-          upstream_http_status: upstream.status,
-          upstream_content_type: upstreamContentType,
-          upstream_body_type: typeof upstream.body,
-          invalid_reason: "missing_response_id"
-        })
-      };
-    }
-    const expectedId = args.requestId ?? null;
-    if (upstreamId !== expectedId) {
-      return {
-        httpStatus: 200,
-        wrapped: true,
-        body: makeWrappedError(args.requestId, "upstream response id mismatch", {
-          failure_class: "upstream_id_mismatch",
-          expected_request_id: expectedId,
-          upstream_response_id: upstreamId
-        })
-      };
+
+// src/upstream/connection-error.ts
+var UPSTREAM_DOCS_URL = "https://github.com/gethelio/helio/blob/main/docs/getting-started.md";
+var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNRESET",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ETIMEDOUT",
+  "EPIPE",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_SOCKET"
+]);
+function extractErrorCode(error) {
+  let current = error;
+  for (let depth = 0; depth < 5 && current != null; depth += 1) {
+    if (typeof current === "object" && "code" in current) {
+      const code = current.code;
+      if (typeof code === "string") return code;
     }
+    current = current.cause;
   }
-  return {
-    httpStatus: 200,
-    wrapped: false,
-    body: upstream.body
-  };
+  return void 0;
+}
+function describeUnreachableUpstream(error, url) {
+  const code = extractErrorCode(error);
+  const isGenericFetchFailure = error instanceof TypeError && error.message === "fetch failed";
+  if (code !== void 0) {
+    if (!UNREACHABLE_CODES.has(code)) return null;
+  } else if (!isGenericFetchFailure) {
+    return null;
+  }
+  const codeSuffix = code ? ` (${code})` : "";
+  return new Error(
+    `Upstream MCP server at ${url} is unreachable${codeSuffix} \u2014 is it running? Helio proxies an existing MCP server: set upstream.url in helio.yaml to a reachable server, or start the server it points at. See ${UPSTREAM_DOCS_URL}`
+  );
 }
 
-// src/transport/streamable-http.ts
-var MCP_SESSION_HEADER = "mcp-session-id";
-var ALLOWED_RESPONSE_HEADERS = /* @__PURE__ */ new Set(["content-type", "mcp-session-id"]);
-function createStreamableHttpRoute(forwarder, options = {}) {
-  const app = new Hono();
-  const forwardHeaderAllowlist = options.forwardHeadersAllowlist ?? [];
-  app.post("/", async (c) => {
-    const contentType = c.req.header("content-type") ?? "";
-    if (!contentType.includes("application/json")) {
-      return c.json(
-        makeJsonRpcError(null, INVALID_REQUEST, "Content-Type must be application/json"),
-        415
-      );
+// src/upstream/sse-parse.ts
+function parseSseChunk(chunk, state, onEvent) {
+  let { event, data, remainder } = state;
+  const text = remainder + chunk;
+  const lines = text.split("\n");
+  remainder = lines.pop() ?? "";
+  for (const rawLine of lines) {
+    const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+    if (line === "") {
+      if (event || data) {
+        onEvent(event, data);
+        event = "";
+        data = "";
+      }
+    } else if (line.startsWith("event:")) {
+      const value = line.slice(6).replace(/^ /, "");
+      event = value;
+    } else if (line.startsWith("data:")) {
+      const value = line.slice(5).replace(/^ /, "");
+      data = data ? data + "\n" + value : value;
     }
-    let body;
+  }
+  return { event, data, remainder };
+}
+async function readSseJsonRpcResponse(res, requestId) {
+  if (!res.body) {
+    throw new Error("upstream SSE response had no body");
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let state = { event: "", data: "", remainder: "" };
+  let found;
+  const onEvent = (event, data) => {
+    if (event && event !== "message") return;
+    let parsed;
     try {
-      body = await c.req.json();
+      parsed = JSON.parse(data);
     } catch {
-      return c.json(makeJsonRpcError(null, PARSE_ERROR, "invalid JSON"), 400);
-    }
-    const parsedRequest = parseJsonRpcRequest(body);
-    if (!parsedRequest.success) {
-      return c.json(makeJsonRpcError(parsedRequest.id, INVALID_REQUEST, parsedRequest.message), 400);
+      return;
     }
-    const id = parsedRequest.request.id;
-    const method = parsedRequest.request.method;
-    const params = parsedRequest.request.params;
-    const sessionId = c.req.header(MCP_SESSION_HEADER);
-    const forwardHeaders = buildForwardHeaders(c.req.raw.headers, forwardHeaderAllowlist);
-    const mcpRequest = {
-      jsonrpc: "2.0",
-      id,
-      method,
-      params,
-      sessionId,
-      headers: forwardHeaders,
-      signal: c.req.raw.signal
-    };
-    if (id === void 0) {
-      const notificationRequest = { ...mcpRequest, signal: void 0 };
-      void forwarder.forward(notificationRequest).catch((err) => {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(`[helio] Upstream notification forward failed (${method}): ${message}`);
-      });
-      return c.body(null, 202);
+    if (parsed === null || typeof parsed !== "object") return;
+    const id = parsed["id"];
+    if (id === requestId) {
+      found = parsed;
     }
-    let result;
-    try {
-      result = await forwarder.forward(mcpRequest);
-    } catch (err) {
-      const forwardingError = err instanceof Error ? err : new Error(String(err));
-      console.error("[helio] Upstream forwarding failed:", forwardingError.message);
-      const normalized2 = normalizeUpstreamOutcome({ requestId: id, forwardingError });
-      return c.json(normalized2.body, normalized2.httpStatus);
+  };
+  const processChunk = (chunk) => {
+    state = parseSseChunk(chunk, state, onEvent);
+  };
+  for (; ; ) {
+    const result = await reader.read();
+    if (result.value !== void 0) {
+      const chunk = result.value;
+      processChunk(decoder.decode(chunk, { stream: true }));
+      if (found) {
+        await reader.cancel().catch(() => void 0);
+        return found;
+      }
     }
-    const { response } = result;
-    for (const [key, value] of Object.entries(response.headers)) {
-      if (ALLOWED_RESPONSE_HEADERS.has(key.toLowerCase())) {
-        c.header(key, value);
+    if (result.done) {
+      const tail = decoder.decode();
+      if (tail) {
+        processChunk(tail);
+        if (found) return found;
       }
+      break;
     }
-    const normalized = normalizeUpstreamOutcome({ requestId: id, upstreamResponse: response });
-    return c.json(normalized.body, normalized.httpStatus);
-  });
-  return app;
+  }
+  throw new Error(
+    `upstream SSE stream closed with no JSON-RPC response for id ${String(requestId)}`
+  );
 }
 
-// src/transport/sse.ts
-import { randomUUID } from "crypto";
-import { Hono as Hono2 } from "hono";
-import { z as z3 } from "zod";
-var encoder = new TextEncoder();
-var STALE_THRESHOLD_MS = 9e4;
-var SWEEP_INTERVAL_MS = 6e4;
-var ssePostQuerySchema = z3.object({
-  sessionId: z3.string().min(1)
-});
-function sseEvent(event, data) {
-  return `event: ${event}
-data: ${data}
-
-`;
+// src/upstream/upstream-session-manager.ts
+var ERA_PROBE_BACKOFF_MS = 3e4;
+var MAX_SSE_SCAN_BYTES = 256 * 1024;
+var ERA_PROBE_REQUEST_ID = "helio-era-probe";
+var MCP_MISSING_CLIENT_CAPABILITY_CODE = -32021;
+var MCP_UNSUPPORTED_PROTOCOL_VERSION_CODE = -32022;
+var MCP_MODERN_ONLY_ERROR_CODES = /* @__PURE__ */ new Set([
+  HEADER_MISMATCH,
+  MCP_MISSING_CLIENT_CAPABILITY_CODE,
+  MCP_UNSUPPORTED_PROTOCOL_VERSION_CODE
+]);
+var MCP_META_PROTOCOL_VERSION_KEY = "io.modelcontextprotocol/protocolVersion";
+function buildInternalMeta() {
+  return {
+    [MCP_META_PROTOCOL_VERSION_KEY]: HELIO_MCP_MODERN_PROTOCOL_VERSION,
+    "io.modelcontextprotocol/clientCapabilities": {},
+    "io.modelcontextprotocol/clientInfo": { name: "helio-proxy", version: "0" }
+  };
 }
-function createSseRoute(forwarder, options = {}) {
-  const sessions = /* @__PURE__ */ new Map();
-  const app = new Hono2();
-  const forwardHeaderAllowlist = options.forwardHeadersAllowlist ?? [];
-  const writeSessionEvent = (sessionId, eventPayload) => {
-    const session = sessions.get(sessionId);
-    if (!session) return;
-    session.lastActivity = Date.now();
-    void session.writer.write(encoder.encode(eventPayload)).catch(() => {
-      sessions.delete(sessionId);
-      void session.writer.close().catch(() => {
-      });
+var UpstreamSessionManager = class {
+  url;
+  staticHeaders;
+  requestTimeoutMs;
+  pin;
+  internal;
+  era;
+  capture;
+  inflight;
+  inflightProbe;
+  probeBackoffUntil = 0;
+  constructor(options) {
+    this.url = options.url;
+    this.staticHeaders = options.staticHeaders;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
+    this.pin = options.protocolVersion ?? "auto";
+  }
+  /** Return the internal session, establishing it once if needed. */
+  ensureInternalSession() {
+    if (this.internal) return Promise.resolve(this.internal);
+    this.inflight ??= this.establish().then((session) => {
+      this.internal = session;
+      return session;
+    }).finally(() => {
+      this.inflight = void 0;
     });
-  };
-  const sweepInterval = setInterval(() => {
-    const now = Date.now();
-    for (const [id, session] of sessions) {
-      if (now - session.lastActivity > STALE_THRESHOLD_MS) {
-        sessions.delete(id);
-        void session.writer.close().catch(() => {
-        });
+    return this.inflight;
+  }
+  /**
+   * Drop the cached internal session and era so the next call re-probes.
+   * Does not cancel any in-flight establishment. Every era wipe drops the
+   * probe-time DiscoverResult capture with it; invalidation is session
+   * lifecycle, not falsification, so it must NOT arm the probe backoff.
+   */
+  invalidateInternalSession() {
+    this.internal = void 0;
+    this.era = void 0;
+    this.capture = void 0;
+  }
+  /**
+   * Resolve the era a relayed request should be sent under. Evaluated in a
+   * strict total order: pin, cached era, join an in-flight probe, backoff
+   * presumption, start a probe. A probe failure never fails the relay — the
+   * request proceeds under a per-request legacy presumption, preserving
+   * today's behavior for deployments the probe cannot classify (for example
+   * per-client Authorization pass-through, where the probe is refused
+   * forever while relays carry the client's own credentials and succeed).
+   */
+  async resolveRelayEra() {
+    const pinned = this.pinnedEra();
+    if (pinned) return pinned;
+    if (this.era) return this.era;
+    const joined = this.inflightProbe;
+    if (joined) {
+      try {
+        const outcome = await joined;
+        this.cacheRelayClassification(outcome);
+        return outcome.era;
+      } catch {
+        return "legacy";
       }
     }
-  }, SWEEP_INTERVAL_MS);
-  sweepInterval.unref();
-  app.get("/", (c) => {
-    const sessionId = randomUUID();
-    const { readable, writable } = new TransformStream();
-    const writer = writable.getWriter();
-    sessions.set(sessionId, { writer, lastActivity: Date.now() });
-    const endpointData = sseEvent("endpoint", `?sessionId=${sessionId}`);
-    writeSessionEvent(sessionId, endpointData);
-    c.req.raw.signal.addEventListener("abort", () => {
-      sessions.delete(sessionId);
-      void writer.close().catch(() => {
-      });
-    });
-    return new Response(readable, {
-      headers: {
-        "content-type": "text/event-stream",
-        "cache-control": "no-cache",
-        connection: "keep-alive"
-      }
-    });
-  });
-  app.post("/", async (c) => {
-    const parsedQuery = ssePostQuerySchema.safeParse(c.req.query());
-    if (!parsedQuery.success) {
-      return c.json(
-        makeJsonRpcError(null, INVALID_REQUEST, "missing sessionId query parameter"),
-        400
-      );
+    if (Date.now() < this.probeBackoffUntil) return "legacy";
+    try {
+      const outcome = await this.sharedProbe();
+      this.cacheRelayClassification(outcome);
+      return outcome.era;
+    } catch {
+      return "legacy";
     }
-    const sessionId = parsedQuery.data.sessionId;
-    const session = sessions.get(sessionId);
-    if (!session) {
-      return c.json(makeJsonRpcError(null, INVALID_REQUEST, "unknown session"), 404);
+  }
+  /**
+   * The falsification door, shared by both sides: a signal just
+   * contradicted a cached LEGACY era — a relayed response only a modern
+   * server gives (a modern-only JSON-RPC code on any method, a 404/-32601
+   * answer to a relayed initialize), or the internal initialize failing
+   * against the classification that promised it would work. No-ops unless
+   * the cached era is 'legacy': a cached modern era is never cleared
+   * automatically — no reliable legacy-rejection signal exists, recovery
+   * from an upstream downgrade is pin-or-restart, and during the
+   * probe-to-initialize window a fresher relay probe may already have
+   * re-classified the upstream as modern, in which case an initialize
+   * failure is evidence against the STALE legacy classification, not
+   * against that newer conclusion.
+   */
+  clearFalsifiedLegacyEra(door) {
+    if (this.era !== "legacy") return;
+    this.clearEraAndArmBackoff(door);
+  }
+  /** Probe-captured DiscoverResult fields for the relay initialize synthesis. */
+  getDiscoverCapture() {
+    return this.capture;
+  }
+  /** The era a non-auto pin dictates; undefined in auto mode. */
+  pinnedEra() {
+    if (this.pin === HELIO_MCP_MODERN_PROTOCOL_VERSION) return "modern";
+    if (this.pin === HELIO_MCP_LEGACY_PROTOCOL_VERSION) return "legacy";
+    return void 0;
+  }
+  /**
+   * One in-flight `server/discover` per manager, shared by `establish()` and
+   * `resolveRelayEra()` — whichever asks first starts it, later callers
+   * join. A failure notes its time, arming the relay-path backoff, then
+   * rethrows for the consumer's own handling.
+   */
+  sharedProbe() {
+    this.inflightProbe ??= this.probeEra().catch((error) => {
+      this.probeBackoffUntil = Date.now() + ERA_PROBE_BACKOFF_MS;
+      throw error;
+    }).finally(() => {
+      this.inflightProbe = void 0;
+    });
+    return this.inflightProbe;
+  }
+  /**
+   * Relay-path caching: the probe classification alone settles the era.
+   * Caching 'legacy' without a proven initialize is what makes
+   * `establish()`'s legacy fast path live; the two-sided re-probe rule
+   * (`clearFalsifiedLegacyEra()` and the internal initialize catch) heals a
+   * wrong conclusion.
+   */
+  cacheRelayClassification(outcome) {
+    if (outcome.era === "modern") {
+      this.cacheModernClassification(outcome);
+      return;
     }
-    const contentType = c.req.header("content-type") ?? "";
-    if (!contentType.includes("application/json")) {
-      return c.json(
-        makeJsonRpcError(null, INVALID_REQUEST, "Content-Type must be application/json"),
-        415
-      );
+    this.setEra("legacy");
+  }
+  /** Every modern classification re-captures from its own fresh DiscoverResult. */
+  cacheModernClassification(outcome) {
+    this.capture = { capabilities: outcome.capabilities, instructions: outcome.instructions };
+    this.setEra("modern");
+  }
+  /**
+   * Falsified-classification clear: any cleared era means the classification
+   * was just contradicted, so re-probing is throttled no matter which door
+   * noticed. No-ops under a pin and on uncached eras; drops the probe-time
+   * DiscoverResult capture with the era it came from; emits exactly one
+   * operator line per clear.
+   */
+  clearEraAndArmBackoff(door) {
+    if (this.pinnedEra()) return;
+    if (this.era === void 0) return;
+    this.era = void 0;
+    this.capture = void 0;
+    this.probeBackoffUntil = Date.now() + ERA_PROBE_BACKOFF_MS;
+    console.error(
+      `[helio] Upstream MCP era cleared: ${door}; relays presume legacy and re-probing is throttled for ${String(ERA_PROBE_BACKOFF_MS / 1e3)}s`
+    );
+  }
+  /** Convert a fetch failure into an actionable error for the given step. */
+  describeFetchFailure(error, step) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+      return new Error(`upstream ${step} timed out after ${String(this.requestTimeoutMs)}ms`);
     }
-    let body;
+    return describeUnreachableUpstream(error, this.url) ?? (error instanceof Error ? error : new Error(String(error)));
+  }
+  async establish() {
+    const pinned = this.pinnedEra();
+    if (pinned === "modern") return this.modernSession();
+    if (pinned === "legacy") return this.legacyInitialize();
+    if (this.era === "modern") return this.modernSession();
+    if (this.era === "legacy") return this.legacyInitializeCachingEra(void 0);
+    const probe = await this.sharedProbe();
+    if (probe.era === "modern") {
+      this.cacheModernClassification(probe);
+      return this.modernSession();
+    }
+    return this.legacyInitializeCachingEra(probe.unsupportedModernVersions);
+  }
+  /** The only `initialize` call site: one handshake attempt per establishment. */
+  async legacyInitializeCachingEra(unsupportedModernVersions) {
     try {
-      body = await c.req.json();
-    } catch {
-      return c.json(makeJsonRpcError(null, PARSE_ERROR, "invalid JSON"), 400);
-    }
-    const parsedRequest = parseJsonRpcRequest(body);
-    if (!parsedRequest.success) {
-      return c.json(makeJsonRpcError(parsedRequest.id, INVALID_REQUEST, parsedRequest.message), 400);
+      const session = await this.legacyInitialize();
+      this.setEra("legacy");
+      return session;
+    } catch (error) {
+      this.clearFalsifiedLegacyEra("internal initialize failed against the cached legacy era");
+      if (unsupportedModernVersions) {
+        throw new Error(
+          `upstream is a modern MCP server supporting [${unsupportedModernVersions.join(", ")}] (helio speaks ${HELIO_MCP_MODERN_PROTOCOL_VERSION} or legacy initialize); legacy fallback also failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+      throw error;
     }
-    const id = parsedRequest.request.id;
-    const method = parsedRequest.request.method;
-    const params = parsedRequest.request.params;
-    const forwardHeaders = buildForwardHeaders(c.req.raw.headers, forwardHeaderAllowlist);
-    const mcpRequest = {
-      jsonrpc: "2.0",
-      id,
-      method,
-      params,
-      sessionId,
-      headers: forwardHeaders,
-      signal: c.req.raw.signal
+  }
+  /** Single owner of era assignment and of the era-detected log line. */
+  setEra(era) {
+    if (this.era === era) return;
+    this.era = era;
+    console.error(
+      era === "modern" ? `[helio] Upstream MCP era detected: modern (${HELIO_MCP_MODERN_PROTOCOL_VERSION}, via server/discover)` : "[helio] Upstream MCP era detected: legacy (initialize handshake)"
+    );
+  }
+  /** A modern upstream neither mints nor echoes session ids — nothing to hold. */
+  modernSession() {
+    return {
+      sessionId: void 0,
+      protocolVersion: HELIO_MCP_MODERN_PROTOCOL_VERSION,
+      era: "modern"
     };
-    if (id === void 0) {
-      const notificationRequest = { ...mcpRequest, signal: void 0 };
-      void forwarder.forward(notificationRequest).catch((err) => {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(`[helio] Upstream notification forward failed (${method}): ${message}`);
+  }
+  /**
+   * Classify the upstream's era with one `server/discover` request.
+   *
+   * A pure classifier: it performs no handshake, so the dual-era salvage cannot
+   * double-initialize. It throws when no era conclusion is possible — a
+   * transport failure, a status that says nothing about the era (401/403/5xx),
+   * or a known-modern server refusing Helio's own probe — leaving the era
+   * uncached so the next attempt re-probes.
+   */
+  async probeEra() {
+    const headers = mergeUpstreamHeaders(
+      {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        "mcp-protocol-version": HELIO_MCP_MODERN_PROTOCOL_VERSION,
+        "mcp-method": "server/discover"
+      },
+      {},
+      this.staticHeaders
+    );
+    headers["mcp-method"] = "server/discover";
+    delete headers["mcp-name"];
+    const probeBody = {
+      jsonrpc: "2.0",
+      id: ERA_PROBE_REQUEST_ID,
+      method: "server/discover",
+      params: { _meta: buildInternalMeta() }
+    };
+    let res;
+    try {
+      res = await fetch(this.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(probeBody),
+        signal: AbortSignal.timeout(this.requestTimeoutMs)
       });
-      return c.body(null, 202);
+    } catch (error) {
+      throw this.describeFetchFailure(error, "server/discover probe");
     }
-    let result;
+    if (!isClassifiableProbeStatus(res.status)) {
+      throw new Error(`upstream server/discover probe failed: HTTP ${String(res.status)}`);
+    }
+    const body = await this.readProbeBody(res);
+    if (body.kind === "stalled") {
+      throw new Error(`upstream server/discover probe ${body.reason}`);
+    }
+    if (body.kind === "unparseable") {
+      return { era: "legacy" };
+    }
+    if (body.kind === "error") {
+      return classifyProbeError(body.envelope);
+    }
+    return classifyProbeResult(body.envelope);
+  }
+  async readProbeBody(res) {
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      if (!res.body) return { kind: "unparseable" };
+      const scan = await this.scanSseEvents(
+        res.body,
+        (payload) => payload["id"] === ERA_PROBE_REQUEST_ID ? payload : void 0
+      );
+      switch (scan.outcome) {
+        case "found":
+          return classifyEnvelopeShape(scan.value);
+        case "closed":
+          return { kind: "unparseable" };
+        case "timed-out":
+          return {
+            kind: "stalled",
+            reason: `SSE response timed out after ${String(this.requestTimeoutMs)}ms`
+          };
+        case "too-large":
+          return {
+            kind: "stalled",
+            reason: `SSE response exceeded ${String(MAX_SSE_SCAN_BYTES)} bytes`
+          };
+      }
+    }
+    const raw = await res.text();
+    if (!raw.trim()) return { kind: "unparseable" };
+    let parsed;
     try {
-      result = await forwarder.forward(mcpRequest);
-    } catch (err) {
-      const forwardingError = err instanceof Error ? err : new Error(String(err));
-      console.error("[helio] Upstream forwarding failed:", forwardingError.message);
-      const normalized2 = normalizeUpstreamOutcome({ requestId: id, forwardingError });
-      const errorEvent = sseEvent("message", JSON.stringify(normalized2.body));
-      writeSessionEvent(sessionId, errorEvent);
-      return c.body(null, 202);
+      parsed = JSON.parse(raw);
+    } catch {
+      return { kind: "unparseable" };
     }
-    const normalized = normalizeUpstreamOutcome({
-      requestId: id,
-      upstreamResponse: result.response
-    });
-    const messageEvent = sseEvent("message", JSON.stringify(normalized.body));
-    writeSessionEvent(sessionId, messageEvent);
-    return c.body(null, 202);
-  });
-  return app;
-}
-
-// src/server.ts
-var FORCE_CONNECTION_CLOSE_GRACE_MS = 1500;
-function normalizeError(error) {
-  if (error instanceof Error) return error;
-  return new Error(String(error));
-}
-function createServerHandle(server) {
-  const sockets = /* @__PURE__ */ new Set();
-  const nodeServer = server;
-  nodeServer.on("connection", (socket) => {
-    sockets.add(socket);
-    socket.on("close", () => {
-      sockets.delete(socket);
+    if (typeof parsed !== "object" || parsed === null) return { kind: "unparseable" };
+    return classifyEnvelopeShape(parsed);
+  }
+  async legacyInitialize() {
+    const headers = mergeUpstreamHeaders(
+      {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream"
+      },
+      {},
+      this.staticHeaders
+    );
+    delete headers["mcp-method"];
+    delete headers["mcp-name"];
+    const initBody = {
+      jsonrpc: "2.0",
+      id: 0,
+      method: "initialize",
+      params: {
+        protocolVersion: HELIO_MCP_LEGACY_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "helio-proxy", version: "0" }
+      }
+    };
+    let res;
+    try {
+      res = await fetch(this.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(initBody),
+        signal: AbortSignal.timeout(this.requestTimeoutMs)
+      });
+    } catch (error) {
+      throw this.describeFetchFailure(error, "initialize");
+    }
+    if (!res.ok) {
+      throw new Error(`upstream initialize failed: HTTP ${String(res.status)}`);
+    }
+    const sessionId = res.headers.get("mcp-session-id") ?? void 0;
+    const initializeEnvelope = await this.readRequiredJsonRpcEnvelope(
+      res,
+      initBody.id,
+      "initialize"
+    );
+    const initializeError = extractJsonRpcErrorMessage(initializeEnvelope);
+    if (initializeError) {
+      throw new Error(`upstream initialize returned JSON-RPC error: ${initializeError}`);
+    }
+    const negotiatedProtocolVersion = extractNegotiatedProtocolVersion(initializeEnvelope);
+    const notifyHeaders = { ...headers };
+    if (sessionId) notifyHeaders["mcp-session-id"] = sessionId;
+    notifyHeaders["mcp-protocol-version"] = negotiatedProtocolVersion;
+    const notifyRes = await fetch(this.url, {
+      method: "POST",
+      headers: notifyHeaders,
+      body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+      signal: AbortSignal.timeout(this.requestTimeoutMs)
+    }).catch((error) => {
+      throw this.describeFetchFailure(error, "notifications/initialized");
     });
-  });
-  const forceCloseConnections = () => {
+    if (!notifyRes.ok) {
+      throw new Error(`upstream notifications/initialized failed: HTTP ${String(notifyRes.status)}`);
+    }
+    const notifyError = await this.readOptionalJsonRpcError(notifyRes);
+    if (notifyError) {
+      throw new Error(`upstream notifications/initialized returned JSON-RPC error: ${notifyError}`);
+    }
+    return { sessionId, protocolVersion: negotiatedProtocolVersion, era: "legacy" };
+  }
+  async readRequiredJsonRpcEnvelope(res, requestId, step) {
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      const payload = await readSseJsonRpcResponse(res, requestId);
+      return payload;
+    }
+    const raw = await res.text();
+    if (!raw.trim()) {
+      throw new Error(`upstream ${step} returned an empty body`);
+    }
+    let parsed;
     try {
-      nodeServer.closeIdleConnections?.();
+      parsed = JSON.parse(raw);
     } catch {
+      throw new Error(`upstream ${step} returned non-JSON body`);
     }
-    if (nodeServer.closeAllConnections) {
-      try {
-        nodeServer.closeAllConnections();
-      } catch {
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new Error(`upstream ${step} returned non-object JSON`);
+    }
+    return parsed;
+  }
+  async readOptionalJsonRpcError(res) {
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      if (!res.body) return void 0;
+      const scan = await this.scanSseEvents(
+        res.body,
+        (payload) => extractJsonRpcErrorMessage(payload)
+      );
+      switch (scan.outcome) {
+        case "found":
+          return scan.value;
+        case "closed":
+          return void 0;
+        case "timed-out":
+          throw new Error(
+            `upstream notifications/initialized SSE response timed out after ${String(this.requestTimeoutMs)}ms`
+          );
+        case "too-large":
+          throw new Error(
+            `upstream notifications/initialized SSE response exceeded ${String(MAX_SSE_SCAN_BYTES)} bytes`
+          );
       }
-      return;
     }
-    for (const socket of sockets) {
-      socket.destroy();
+    const raw = await res.text();
+    if (!raw.trim()) return void 0;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return void 0;
     }
-  };
-  return {
-    server,
-    close: () => new Promise((resolve2, reject) => {
-      let settled = false;
-      let forceTimer;
-      const settle = (err) => {
-        if (settled) return;
-        settled = true;
-        if (forceTimer) {
-          clearTimeout(forceTimer);
-          forceTimer = void 0;
-        }
-        if (err) {
-          reject(err);
-          return;
-        }
-        resolve2();
-      };
+    if (typeof parsed !== "object" || parsed === null) return void 0;
+    return extractJsonRpcErrorMessage(parsed);
+  }
+  /**
+   * Read an SSE POST response body under an explicit read deadline and byte
+   * cap, returning the first `message` payload `select` accepts. The
+   * fetch-level `AbortSignal.timeout` would eventually abort a stalled body
+   * read; these bounds are the belt to its braces.
+   */
+  async scanSseEvents(body, select) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let state = { event: "", data: "", remainder: "" };
+    let found;
+    let scannedBytes = 0;
+    const deadline = Date.now() + this.requestTimeoutMs;
+    const onEvent = (event, data) => {
+      if (found !== void 0) return;
+      if (event && event !== "message") return;
+      let parsed;
       try {
-        nodeServer.close((err) => {
-          if (err) {
-            settle(err);
-            return;
-          }
-          settle();
-        });
-      } catch (error) {
-        settle(normalizeError(error));
+        parsed = JSON.parse(data);
+      } catch {
         return;
       }
+      if (typeof parsed !== "object" || parsed === null) return;
+      found = select(parsed);
+    };
+    for (; ; ) {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        await reader.cancel().catch(() => void 0);
+        return { outcome: "timed-out" };
+      }
+      let chunk;
       try {
-        nodeServer.closeIdleConnections?.();
+        chunk = await readSseChunkWithTimeout(reader, remainingMs);
       } catch {
+        await reader.cancel().catch(() => void 0);
+        return { outcome: "timed-out" };
       }
-      forceTimer = setTimeout(() => {
-        forceCloseConnections();
-      }, FORCE_CONNECTION_CLOSE_GRACE_MS);
-      forceTimer.unref();
-    })
-  };
-}
-function createApp(config, forwarder, options) {
-  const app = new Hono3();
-  const forwardHeadersAllowlist = config.upstream.forward_headers;
-  app.get("/healthz", (c) => c.json({ status: "ok" }));
-  app.route("/mcp", createStreamableHttpRoute(forwarder, { forwardHeadersAllowlist }));
-  app.route("/sse", createSseRoute(forwarder, { forwardHeadersAllowlist }));
-  if (options?.slackActionApp) {
-    app.route("/slack/actions", options.slackActionApp);
+      const { done, value } = chunk;
+      if (value !== void 0) {
+        scannedBytes += value.byteLength;
+        if (scannedBytes > MAX_SSE_SCAN_BYTES) {
+          await reader.cancel().catch(() => void 0);
+          return { outcome: "too-large" };
+        }
+        state = parseSseChunk(decoder.decode(value, { stream: true }), state, onEvent);
+        if (found !== void 0) {
+          await reader.cancel().catch(() => void 0);
+          return { outcome: "found", value: found };
+        }
+      }
+      if (done) {
+        const tail = decoder.decode();
+        if (tail) {
+          state = parseSseChunk(tail, state, onEvent);
+        }
+        return found !== void 0 ? { outcome: "found", value: found } : { outcome: "closed" };
+      }
+    }
+  }
+};
+async function readSseChunkWithTimeout(reader, timeoutMs) {
+  let timeoutHandle;
+  try {
+    const result = await Promise.race([
+      reader.read(),
+      new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => {
+          reject(new Error(`sse read timed out after ${String(timeoutMs)}ms`));
+        }, timeoutMs);
+      })
+    ]);
+    if (!isSseReadChunk(result)) {
+      throw new Error("upstream SSE response returned invalid chunk");
+    }
+    return result;
+  } finally {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
   }
-  return app;
 }
-function startServer(app, config) {
-  const server = serve({
-    fetch: app.fetch,
-    port: config.listen.port,
-    hostname: config.listen.host
-  });
-  return createServerHandle(server);
+function isSseReadChunk(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  if (typeof candidate.done !== "boolean") return false;
+  if (candidate.value === void 0) return true;
+  return candidate.value instanceof Uint8Array;
 }
-function startSidebandServer(app, port, host = "127.0.0.1") {
-  const server = serve({
-    fetch: app.fetch,
-    port,
-    hostname: host
-  });
-  return createServerHandle(server);
+function isClassifiableProbeStatus(status) {
+  if (status >= 200 && status < 300) return true;
+  return status === 400 || status === 404 || status === 405;
 }
-
-// src/upstream/response.ts
-async function parseUpstreamResponse(res) {
-  const headers = {};
-  res.headers.forEach((value, key) => {
-    headers[key] = value;
-  });
-  const contentType = res.headers.get("content-type") ?? "";
-  let body;
-  if (contentType.includes("application/json")) {
-    const text = await res.text();
-    try {
-      body = JSON.parse(text);
-    } catch {
-      body = text;
-    }
-  } else {
-    body = await res.text();
+function classifyEnvelopeShape(envelope) {
+  if (envelope["error"] !== void 0) return { kind: "error", envelope };
+  if (envelope["result"] !== void 0) return { kind: "result", envelope };
+  return { kind: "unparseable" };
+}
+function classifyProbeError(envelope) {
+  const error = envelope["error"];
+  const code = typeof error === "object" && error !== null ? error["code"] : void 0;
+  if (code === MCP_UNSUPPORTED_PROTOCOL_VERSION_CODE) {
+    const data = error["data"];
+    return {
+      era: "legacy",
+      unsupportedModernVersions: readStringArray(
+        typeof data === "object" && data !== null ? data["supported"] : void 0
+      )
+    };
   }
-  return { status: res.status, headers, body };
+  if (code === HEADER_MISMATCH || code === MCP_MISSING_CLIENT_CAPABILITY_CODE) {
+    throw new Error(
+      `upstream refused Helio's server/discover probe with modern MCP error ${String(code)}: ${extractJsonRpcErrorMessage(envelope) ?? "unknown JSON-RPC error"} (the upstream is a modern MCP server, so Helio does not fall back to initialize)`
+    );
+  }
+  return { era: "legacy" };
 }
-
-// src/upstream/sse-parse.ts
-function parseSseChunk(chunk, state, onEvent) {
-  let { event, data, remainder } = state;
-  const text = remainder + chunk;
-  const lines = text.split("\n");
-  remainder = lines.pop() ?? "";
-  for (const rawLine of lines) {
-    const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
-    if (line === "") {
-      if (event || data) {
-        onEvent(event, data);
-        event = "";
-        data = "";
-      }
-    } else if (line.startsWith("event:")) {
-      const value = line.slice(6).replace(/^ /, "");
-      event = value;
-    } else if (line.startsWith("data:")) {
-      const value = line.slice(5).replace(/^ /, "");
-      data = data ? data + "\n" + value : value;
-    }
+function classifyProbeResult(envelope) {
+  const result = envelope["result"];
+  if (typeof result !== "object" || result === null) return { era: "legacy" };
+  const supportedVersions = result["supportedVersions"];
+  if (!Array.isArray(supportedVersions)) {
+    return { era: "legacy" };
   }
-  return { event, data, remainder };
+  const versions = readStringArray(supportedVersions);
+  if (versions.includes(HELIO_MCP_MODERN_PROTOCOL_VERSION)) {
+    const record = result;
+    const capabilities = record["capabilities"];
+    const instructions = record["instructions"];
+    return {
+      era: "modern",
+      capabilities: typeof capabilities === "object" && capabilities !== null && !Array.isArray(capabilities) ? capabilities : void 0,
+      instructions: typeof instructions === "string" ? instructions : void 0
+    };
+  }
+  return { era: "legacy", unsupportedModernVersions: versions };
 }
-async function readSseJsonRpcResponse(res, requestId) {
-  if (!res.body) {
-    throw new Error("upstream SSE response had no body");
+function readStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => typeof entry === "string");
+}
+function extractJsonRpcErrorMessage(payload) {
+  const error = payload["error"];
+  if (typeof error === "string") return error;
+  if (typeof error !== "object" || error === null) return void 0;
+  const message = error["message"];
+  if (typeof message === "string" && message.trim()) return message;
+  return "unknown JSON-RPC error";
+}
+function extractNegotiatedProtocolVersion(payload) {
+  const result = payload["result"];
+  if (typeof result !== "object" || result === null) {
+    return HELIO_MCP_LEGACY_PROTOCOL_VERSION;
   }
-  const reader = res.body.getReader();
-  const decoder = new TextDecoder();
-  let state = { event: "", data: "", remainder: "" };
-  let found;
-  const onEvent = (event, data) => {
-    if (event && event !== "message") return;
-    let parsed;
-    try {
-      parsed = JSON.parse(data);
-    } catch {
-      return;
+  const protocolVersion = result["protocolVersion"];
+  return typeof protocolVersion === "string" && protocolVersion.trim() ? protocolVersion : HELIO_MCP_LEGACY_PROTOCOL_VERSION;
+}
+
+// src/transport/header-body-agreement.ts
+var DISPLAY_CAP_CHARS = 256;
+function displayCap(value) {
+  if (value.length <= DISPLAY_CAP_CHARS) return value;
+  return `${value.slice(0, DISPLAY_CAP_CHARS)}\u2026 (truncated)`;
+}
+function readOwnField(source, field) {
+  if (typeof source !== "object" || source === null || Array.isArray(source)) return void 0;
+  if (!Object.prototype.hasOwnProperty.call(source, field)) return void 0;
+  return source[field];
+}
+function validateHeaderBodyAgreement(input) {
+  const { method, params } = input;
+  const headerMethod = input.headers["mcp-method"];
+  const headerName = input.headers["mcp-name"];
+  const rawVersionClaim = input.headers["mcp-protocol-version"];
+  const modern = isModernProtocolClaim(rawVersionClaim);
+  const isNotification = input.id === void 0;
+  const requiresPresence = modern && !isNotification;
+  const field = nameBearingField(method);
+  const rawFieldValue = field === void 0 ? void 0 : readOwnField(params, field);
+  const bodyName = typeof rawFieldValue === "string" ? rawFieldValue : void 0;
+  const presentHeaders = {};
+  if (headerMethod !== void 0) presentHeaders["mcp-method"] = headerMethod;
+  if (headerName !== void 0) presentHeaders["mcp-name"] = headerName;
+  if (rawVersionClaim !== void 0) presentHeaders["mcp-protocol-version"] = rawVersionClaim;
+  const reject = (reason) => ({
+    ok: false,
+    reason,
+    evidence: {
+      headers: presentHeaders,
+      ...bodyName !== void 0 && { bodyName }
     }
-    if (parsed === null || typeof parsed !== "object") return;
-    const id = parsed["id"];
-    if (id === requestId) {
-      found = parsed;
+  });
+  if (headerMethod === void 0) {
+    if (requiresPresence) {
+      return reject(`missing mcp-method header (expected ${displayCap(method)})`);
     }
-  };
-  const processChunk = (chunk) => {
-    state = parseSseChunk(chunk, state, onEvent);
-  };
-  for (; ; ) {
-    const result = await reader.read();
-    if (result.value !== void 0) {
-      const chunk = result.value;
-      processChunk(decoder.decode(chunk, { stream: true }));
-      if (found) {
-        await reader.cancel().catch(() => void 0);
-        return found;
+  } else if (headerMethod !== method) {
+    return reject(
+      `mismatched mcp-method header (expected ${displayCap(method)}, got ${displayCap(headerMethod)})`
+    );
+  }
+  if (bodyName !== void 0) {
+    if (headerName === void 0) {
+      if (requiresPresence) {
+        return reject(`missing mcp-name header (expected ${displayCap(bodyName)})`);
+      }
+    } else {
+      const decoded = decodeSentinelValue(headerName);
+      if (decoded !== bodyName) {
+        return reject(
+          `mismatched mcp-name header (expected ${displayCap(bodyName)}, got ${displayCap(decoded)})`
+        );
       }
     }
-    if (result.done) {
-      const tail = decoder.decode();
-      if (tail) {
-        processChunk(tail);
-        if (found) return found;
+  }
+  if (modern) {
+    const mirror = readOwnField(readOwnField(params, "_meta"), MCP_META_PROTOCOL_VERSION_KEY);
+    if (mirror === void 0) {
+      if (!isNotification) {
+        return reject(
+          `missing params._meta["${MCP_META_PROTOCOL_VERSION_KEY}"] mirror (expected ${HELIO_MCP_MODERN_PROTOCOL_VERSION})`
+        );
       }
-      break;
+    } else if (mirror !== HELIO_MCP_MODERN_PROTOCOL_VERSION) {
+      const display = typeof mirror === "string" ? mirror : JSON.stringify(mirror);
+      return reject(
+        `mismatched params._meta["${MCP_META_PROTOCOL_VERSION_KEY}"] mirror (expected ${HELIO_MCP_MODERN_PROTOCOL_VERSION}, got ${displayCap(display)})`
+      );
     }
   }
-  throw new Error(
-    `upstream SSE stream closed with no JSON-RPC response for id ${String(requestId)}`
-  );
+  return { ok: true };
 }
 
-// src/upstream/merge-headers.ts
-function mergeUpstreamHeaders(base, forwarded, staticHeaders) {
-  const out = {};
-  const apply = (headers) => {
-    for (const [name, value] of Object.entries(headers)) {
-      out[name.toLowerCase()] = value;
+// src/transport/origin-guard.ts
+var MAX_UNIQUE_ORIGIN_WARNINGS = 20;
+var SUPPRESSED_WARNING_SUMMARY_INTERVAL = 50;
+var LOGGED_ORIGIN_MAX_LENGTH = 256;
+function createOriginGuard(allowedOrigins) {
+  const allowed = new Set(allowedOrigins);
+  const warnedOrigins = /* @__PURE__ */ new Set();
+  let suppressedWarningCount = 0;
+  const logRejection = (origin) => {
+    const displayOrigin = origin.length > LOGGED_ORIGIN_MAX_LENGTH ? `${origin.slice(0, LOGGED_ORIGIN_MAX_LENGTH)}\u2026 (truncated)` : origin;
+    if (warnedOrigins.has(displayOrigin)) return;
+    if (warnedOrigins.size < MAX_UNIQUE_ORIGIN_WARNINGS) {
+      warnedOrigins.add(displayOrigin);
+      console.error(`[helio] Rejected request with disallowed Origin: ${displayOrigin}`);
+      return;
+    }
+    suppressedWarningCount += 1;
+    if (suppressedWarningCount === 1 || suppressedWarningCount % SUPPRESSED_WARNING_SUMMARY_INTERVAL === 0) {
+      console.error(
+        `[helio] Origin rejection warnings: logged ${String(MAX_UNIQUE_ORIGIN_WARNINGS)} distinct origins and are suppressing the rest (${String(suppressedWarningCount)} further rejections so far).`
+      );
     }
   };
-  apply(base);
-  apply(forwarded);
-  apply(staticHeaders);
-  return out;
+  return async (c, next) => {
+    const origin = c.req.header("origin");
+    if (origin !== void 0 && !allowed.has(origin)) {
+      logRejection(origin);
+      return c.json(makeJsonRpcErrorWithoutId(INVALID_REQUEST, "Origin not allowed"), 403);
+    }
+    await next();
+  };
 }
 
-// src/upstream/connection-error.ts
-var UPSTREAM_DOCS_URL = "https://github.com/gethelio/helio/blob/main/docs/getting-started.md";
-var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
-  "ECONNREFUSED",
-  "ENOTFOUND",
-  "EAI_AGAIN",
-  "ECONNRESET",
-  "EHOSTUNREACH",
-  "ENETUNREACH",
-  "ETIMEDOUT",
-  "EPIPE",
-  "UND_ERR_CONNECT_TIMEOUT",
-  "UND_ERR_SOCKET"
-]);
-function extractErrorCode(error) {
-  let current = error;
-  for (let depth = 0; depth < 5 && current != null; depth += 1) {
-    if (typeof current === "object" && "code" in current) {
-      const code = current.code;
-      if (typeof code === "string") return code;
-    }
-    current = current.cause;
-  }
-  return void 0;
+// src/transport/response-normalizer.ts
+function isObject(value) {
+  return value !== null && typeof value === "object";
 }
-function describeUnreachableUpstream(error, url) {
-  const code = extractErrorCode(error);
-  const isGenericFetchFailure = error instanceof TypeError && error.message === "fetch failed";
-  if (code !== void 0) {
-    if (!UNREACHABLE_CODES.has(code)) return null;
-  } else if (!isGenericFetchFailure) {
-    return null;
-  }
-  const codeSuffix = code ? ` (${code})` : "";
-  return new Error(
-    `Upstream MCP server at ${url} is unreachable${codeSuffix} \u2014 is it running? Helio proxies an existing MCP server: set upstream.url in helio.yaml to a reachable server, or start the server it points at. See ${UPSTREAM_DOCS_URL}`
-  );
+function isValidJsonRpcId(value) {
+  return value === null || typeof value === "string" || typeof value === "number";
 }
-
-// src/upstream/upstream-session-manager.ts
-var HELIO_MCP_PROTOCOL_VERSION = "2025-06-18";
-var MAX_SSE_ERROR_SCAN_BYTES = 256 * 1024;
-var UpstreamSessionManager = class {
-  url;
-  staticHeaders;
-  requestTimeoutMs;
-  internal;
-  inflight;
-  constructor(options) {
-    this.url = options.url;
-    this.staticHeaders = options.staticHeaders;
-    this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
-  }
-  /** Return the internal session, performing the handshake once if needed. */
-  ensureInternalSession() {
-    if (this.internal) return Promise.resolve(this.internal);
-    this.inflight ??= this.initialize().then((session) => {
-      this.internal = session;
-      return session;
-    }).finally(() => {
-      this.inflight = void 0;
-    });
-    return this.inflight;
-  }
-  /**
-   * Drop the cached internal session so the next call re-initializes.
-   * Does not cancel any in-flight initialize.
-   */
-  invalidateInternalSession() {
-    this.internal = void 0;
+function getJsonRpcId(value) {
+  if (!isObject(value) || !Object.prototype.hasOwnProperty.call(value, "id")) return void 0;
+  const id = value["id"];
+  return isValidJsonRpcId(id) ? id : void 0;
+}
+function isValidJsonRpcError(value) {
+  if (!isObject(value)) return false;
+  return typeof value["code"] === "number" && typeof value["message"] === "string";
+}
+function isValidJsonRpcResponse(value) {
+  if (!isObject(value)) return false;
+  if (value["jsonrpc"] !== "2.0") return false;
+  if (Object.prototype.hasOwnProperty.call(value, "id") && !isValidJsonRpcId(value["id"])) {
+    return false;
   }
-  /** Convert a fetch failure into an actionable error for the given step. */
-  describeFetchFailure(error, step) {
-    if (error instanceof Error && error.name === "TimeoutError") {
-      return new Error(`upstream ${step} timed out after ${String(this.requestTimeoutMs)}ms`);
-    }
-    return describeUnreachableUpstream(error, this.url) ?? (error instanceof Error ? error : new Error(String(error)));
+  const hasResult = Object.prototype.hasOwnProperty.call(value, "result");
+  const hasError = Object.prototype.hasOwnProperty.call(value, "error");
+  if (hasResult && hasError || !hasResult && !hasError) return false;
+  if (hasError && !isValidJsonRpcError(value["error"])) return false;
+  return true;
+}
+function makeWrappedError(requestId, message, data) {
+  return {
+    jsonrpc: "2.0",
+    id: requestId ?? null,
+    error: {
+      code: INTERNAL_ERROR,
+      message,
+      data
+    }
+  };
+}
+function normalizeUpstreamOutcome(args) {
+  if (args.forwardingError) {
+    return {
+      httpStatus: 200,
+      wrapped: true,
+      body: makeWrappedError(args.requestId, "upstream forwarding failed", {
+        failure_class: "upstream_forward_error",
+        failure_reason: args.forwardingError.message
+      })
+    };
   }
-  async initialize() {
-    const headers = mergeUpstreamHeaders(
+  if (!args.upstreamResponse) {
+    return {
+      httpStatus: 200,
+      wrapped: true,
+      body: makeWrappedError(args.requestId, "upstream forwarding failed", {
+        failure_class: "upstream_forward_error",
+        failure_reason: "missing upstream response"
+      })
+    };
+  }
+  const upstream = args.upstreamResponse;
+  const upstreamContentType = upstream.headers["content-type"] ?? null;
+  if (!isValidJsonRpcResponse(upstream.body)) {
+    return {
+      httpStatus: 200,
+      wrapped: true,
+      body: makeWrappedError(args.requestId, "upstream returned invalid JSON-RPC response", {
+        failure_class: "upstream_invalid_jsonrpc",
+        upstream_http_status: upstream.status,
+        upstream_content_type: upstreamContentType,
+        upstream_body_type: typeof upstream.body
+      })
+    };
+  }
+  if (args.requestId !== void 0) {
+    const upstreamId = getJsonRpcId(upstream.body);
+    if (upstreamId === void 0) {
+      return {
+        httpStatus: 200,
+        wrapped: true,
+        body: makeWrappedError(args.requestId, "upstream returned invalid JSON-RPC response", {
+          failure_class: "upstream_invalid_jsonrpc",
+          upstream_http_status: upstream.status,
+          upstream_content_type: upstreamContentType,
+          upstream_body_type: typeof upstream.body,
+          invalid_reason: "missing_response_id"
+        })
+      };
+    }
+    const expectedId = args.requestId ?? null;
+    if (upstreamId !== expectedId) {
+      return {
+        httpStatus: 200,
+        wrapped: true,
+        body: makeWrappedError(args.requestId, "upstream response id mismatch", {
+          failure_class: "upstream_id_mismatch",
+          expected_request_id: expectedId,
+          upstream_response_id: upstreamId
+        })
+      };
+    }
+  }
+  return {
+    httpStatus: 200,
+    wrapped: false,
+    body: upstream.body
+  };
+}
+
+// src/transport/streamable-http.ts
+var MCP_SESSION_HEADER = "mcp-session-id";
+var ALLOWED_RESPONSE_HEADERS = /* @__PURE__ */ new Set(["content-type", "mcp-session-id"]);
+function createStreamableHttpRoute(forwarder, options = {}) {
+  const app = new Hono();
+  const forwardHeaderAllowlist = options.forwardHeadersAllowlist ?? [];
+  const sessionIdentity = options.session ?? DEFAULT_SESSION_IDENTITY;
+  app.use("*", createOriginGuard(options.allowedOrigins ?? []));
+  app.post("/", async (c) => {
+    const handlerStart = performance.now();
+    if (!isJsonContentType(c.req.header("content-type"))) {
+      return c.json(
+        makeJsonRpcErrorWithoutId(INVALID_REQUEST, "Content-Type must be application/json"),
+        415
+      );
+    }
+    let body;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json(makeJsonRpcErrorWithoutId(PARSE_ERROR, "invalid JSON"), 400);
+    }
+    const parsedRequest = parseJsonRpcRequest(body);
+    if (!parsedRequest.success) {
+      const errorBody = parsedRequest.id === null ? makeJsonRpcErrorWithoutId(INVALID_REQUEST, parsedRequest.message) : makeJsonRpcError(parsedRequest.id, INVALID_REQUEST, parsedRequest.message);
+      return c.json(errorBody, 400);
+    }
+    const id = parsedRequest.request.id;
+    const method = parsedRequest.request.method;
+    const params = parsedRequest.request.params;
+    const transportSessionId = c.req.header(MCP_SESSION_HEADER);
+    const session = resolveSession(
       {
-        "content-type": "application/json",
-        accept: "application/json, text/event-stream"
+        headers: Object.fromEntries(c.req.raw.headers),
+        meta: paramsMeta(params),
+        transportSessionId
       },
-      {},
-      this.staticHeaders
+      sessionIdentity
     );
-    const initBody = {
-      jsonrpc: "2.0",
-      id: 0,
-      method: "initialize",
-      params: {
-        protocolVersion: HELIO_MCP_PROTOCOL_VERSION,
-        capabilities: {},
-        clientInfo: { name: "helio-proxy", version: "0" }
+    const protocolVersion = c.req.header("mcp-protocol-version");
+    const agreement = validateHeaderBodyAgreement({
+      method,
+      id,
+      params,
+      headers: {
+        "mcp-method": c.req.header("mcp-method"),
+        "mcp-name": c.req.header("mcp-name"),
+        "mcp-protocol-version": protocolVersion
       }
+    });
+    if (!agreement.ok) {
+      options.onHeaderMismatch?.({
+        reason: agreement.reason,
+        method,
+        params,
+        ...agreement.evidence.bodyName !== void 0 && { bodyName: agreement.evidence.bodyName },
+        ...protocolVersion !== void 0 && { protocolVersion },
+        headers: agreement.evidence.headers,
+        ...session !== void 0 && { session },
+        durationMs: performance.now() - handlerStart
+      });
+      const errorBody = id === void 0 || id === null ? makeJsonRpcErrorWithoutId(HEADER_MISMATCH, agreement.reason) : makeJsonRpcError(id, HEADER_MISMATCH, agreement.reason);
+      return c.json(errorBody, 400);
+    }
+    const forwardHeaders = buildForwardHeaders(c.req.raw.headers, forwardHeaderAllowlist);
+    const mcpRequest = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      params,
+      session,
+      transportSessionId,
+      protocolVersion,
+      headers: forwardHeaders,
+      signal: c.req.raw.signal
     };
-    let res;
-    try {
-      res = await fetch(this.url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(initBody),
-        signal: AbortSignal.timeout(this.requestTimeoutMs)
+    if (id === void 0) {
+      const notificationRequest = { ...mcpRequest, signal: void 0 };
+      void forwarder.forward(notificationRequest).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[helio] Upstream notification forward failed (${method}): ${message}`);
       });
-    } catch (error) {
-      throw this.describeFetchFailure(error, "initialize");
+      return c.body(null, 202);
     }
-    if (!res.ok) {
-      throw new Error(`upstream initialize failed: HTTP ${String(res.status)}`);
+    let result;
+    try {
+      result = await forwarder.forward(mcpRequest);
+    } catch (err) {
+      const forwardingError = err instanceof Error ? err : new Error(String(err));
+      console.error("[helio] Upstream forwarding failed:", forwardingError.message);
+      const normalized2 = normalizeUpstreamOutcome({ requestId: id, forwardingError });
+      return c.json(normalized2.body, normalized2.httpStatus);
     }
-    const sessionId = res.headers.get("mcp-session-id") ?? void 0;
-    const initializeEnvelope = await this.readRequiredJsonRpcEnvelope(
-      res,
-      initBody.id,
-      "initialize"
-    );
-    const initializeError = extractJsonRpcErrorMessage(initializeEnvelope);
-    if (initializeError) {
-      throw new Error(`upstream initialize returned JSON-RPC error: ${initializeError}`);
+    const { response } = result;
+    for (const [key, value] of Object.entries(response.headers)) {
+      if (ALLOWED_RESPONSE_HEADERS.has(key.toLowerCase())) {
+        c.header(key, value);
+      }
     }
-    const negotiatedProtocolVersion = extractNegotiatedProtocolVersion(initializeEnvelope);
-    const notifyHeaders = { ...headers };
-    if (sessionId) notifyHeaders["mcp-session-id"] = sessionId;
-    notifyHeaders["mcp-protocol-version"] = negotiatedProtocolVersion;
-    const notifyRes = await fetch(this.url, {
-      method: "POST",
-      headers: notifyHeaders,
-      body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
-      signal: AbortSignal.timeout(this.requestTimeoutMs)
-    }).catch((error) => {
-      throw this.describeFetchFailure(error, "notifications/initialized");
+    const normalized = normalizeUpstreamOutcome({ requestId: id, upstreamResponse: response });
+    return c.json(normalized.body, normalized.httpStatus);
+  });
+  return app;
+}
+
+// src/transport/sse.ts
+import { randomUUID } from "crypto";
+import { Hono as Hono2 } from "hono";
+import { z as z3 } from "zod";
+var encoder = new TextEncoder();
+var MCP_SESSION_HEADER2 = "mcp-session-id";
+var STALE_THRESHOLD_MS = 9e4;
+var SWEEP_INTERVAL_MS = 6e4;
+var MAX_CONCURRENT_SESSIONS = 1024;
+var REFUSAL_LOG_WINDOW_MS = 1e4;
+var ssePostQuerySchema = z3.object({
+  sessionId: z3.string().min(1)
+});
+function sseEvent(event, data) {
+  return `event: ${event}
+data: ${data}
+
+`;
+}
+function createSseRoute(forwarder, options = {}) {
+  const sessions = /* @__PURE__ */ new Map();
+  const app = new Hono2();
+  const forwardHeaderAllowlist = options.forwardHeadersAllowlist ?? [];
+  const sessionIdentity = options.session ?? DEFAULT_SESSION_IDENTITY;
+  const maxConcurrentSessions = options.maxConcurrentSessions ?? MAX_CONCURRENT_SESSIONS;
+  let refusalCount = 0;
+  let lastRefusalLogAt = null;
+  const logRefusal = () => {
+    refusalCount += 1;
+    const now = Date.now();
+    if (lastRefusalLogAt !== null && now - lastRefusalLogAt < REFUSAL_LOG_WINDOW_MS) return;
+    lastRefusalLogAt = now;
+    console.error(
+      `[helio] /sse at session cap (${String(maxConcurrentSessions)}); refusing new streams (${String(refusalCount)} refusals so far).`
+    );
+  };
+  app.use("*", createOriginGuard(options.allowedOrigins ?? []));
+  const writeSessionEvent = (sessionId, eventPayload) => {
+    const session = sessions.get(sessionId);
+    if (!session) return;
+    session.lastActivity = Date.now();
+    void session.writer.write(encoder.encode(eventPayload)).catch(() => {
+      sessions.delete(sessionId);
+      void session.writer.close().catch(() => {
+      });
     });
-    if (!notifyRes.ok) {
-      throw new Error(`upstream notifications/initialized failed: HTTP ${String(notifyRes.status)}`);
+  };
+  const sweepInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [id, session] of sessions) {
+      if (now - session.lastActivity > STALE_THRESHOLD_MS) {
+        sessions.delete(id);
+        void session.writer.close().catch(() => {
+        });
+      }
     }
-    const notifyError = await this.readOptionalJsonRpcError(notifyRes);
-    if (notifyError) {
-      throw new Error(`upstream notifications/initialized returned JSON-RPC error: ${notifyError}`);
+  }, SWEEP_INTERVAL_MS);
+  sweepInterval.unref();
+  app.get("/", (c) => {
+    if (sessions.size >= maxConcurrentSessions) {
+      logRefusal();
+      return c.json({ error: "session capacity reached" }, 503);
     }
-    return { sessionId, protocolVersion: negotiatedProtocolVersion };
-  }
-  async readRequiredJsonRpcEnvelope(res, requestId, step) {
-    const contentType = res.headers.get("content-type") ?? "";
-    if (contentType.includes("text/event-stream")) {
-      const payload = await readSseJsonRpcResponse(res, requestId);
-      return payload;
+    const sessionId = randomUUID();
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    sessions.set(sessionId, { writer, lastActivity: Date.now() });
+    const endpointData = sseEvent("endpoint", `?sessionId=${sessionId}`);
+    writeSessionEvent(sessionId, endpointData);
+    c.req.raw.signal.addEventListener("abort", () => {
+      sessions.delete(sessionId);
+      void writer.close().catch(() => {
+      });
+    });
+    return new Response(readable, {
+      headers: {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive"
+      }
+    });
+  });
+  app.post("/", async (c) => {
+    const parsedQuery = ssePostQuerySchema.safeParse(c.req.query());
+    if (!parsedQuery.success) {
+      return c.json(
+        makeJsonRpcErrorWithoutId(INVALID_REQUEST, "missing sessionId query parameter"),
+        400
+      );
     }
-    const raw = await res.text();
-    if (!raw.trim()) {
-      throw new Error(`upstream ${step} returned an empty body`);
+    const sessionId = parsedQuery.data.sessionId;
+    const session = sessions.get(sessionId);
+    if (!session) {
+      return c.json(makeJsonRpcErrorWithoutId(INVALID_REQUEST, "unknown session"), 404);
     }
-    let parsed;
+    if (!isJsonContentType(c.req.header("content-type"))) {
+      return c.json(
+        makeJsonRpcErrorWithoutId(INVALID_REQUEST, "Content-Type must be application/json"),
+        415
+      );
+    }
+    let body;
     try {
-      parsed = JSON.parse(raw);
+      body = await c.req.json();
     } catch {
-      throw new Error(`upstream ${step} returned non-JSON body`);
+      return c.json(makeJsonRpcErrorWithoutId(PARSE_ERROR, "invalid JSON"), 400);
     }
-    if (typeof parsed !== "object" || parsed === null) {
-      throw new Error(`upstream ${step} returned non-object JSON`);
+    const parsedRequest = parseJsonRpcRequest(body);
+    if (!parsedRequest.success) {
+      const errorBody = parsedRequest.id === null ? makeJsonRpcErrorWithoutId(INVALID_REQUEST, parsedRequest.message) : makeJsonRpcError(parsedRequest.id, INVALID_REQUEST, parsedRequest.message);
+      return c.json(errorBody, 400);
     }
-    return parsed;
-  }
-  async readOptionalJsonRpcError(res) {
-    const contentType = res.headers.get("content-type") ?? "";
-    if (contentType.includes("text/event-stream")) {
-      if (!res.body) return void 0;
-      let errorMessage;
-      const reader = res.body.getReader();
-      const decoder = new TextDecoder();
-      let state = { event: "", data: "", remainder: "" };
-      let scannedBytes = 0;
-      const deadline = Date.now() + this.requestTimeoutMs;
-      const onEvent = (event, data) => {
-        if (errorMessage) return;
-        if (event && event !== "message") return;
-        let parsed2;
-        try {
-          parsed2 = JSON.parse(data);
-        } catch {
+    const id = parsedRequest.request.id;
+    const method = parsedRequest.request.method;
+    const params = parsedRequest.request.params;
+    const forwardHeaders = buildForwardHeaders(c.req.raw.headers, forwardHeaderAllowlist);
+    const transportSessionId = c.req.header(MCP_SESSION_HEADER2);
+    const resolvedSession = resolveSession(
+      {
+        headers: Object.fromEntries(c.req.raw.headers),
+        meta: paramsMeta(params),
+        transportSessionId,
+        transportMintedId: sessionId
+      },
+      sessionIdentity
+    );
+    const mcpRequest = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      params,
+      session: resolvedSession,
+      transportSessionId,
+      headers: forwardHeaders,
+      signal: c.req.raw.signal
+    };
+    if (id === void 0) {
+      const notificationRequest = { ...mcpRequest, signal: void 0 };
+      void forwarder.forward(notificationRequest).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[helio] Upstream notification forward failed (${method}): ${message}`);
+      });
+      return c.body(null, 202);
+    }
+    let result;
+    try {
+      result = await forwarder.forward(mcpRequest);
+    } catch (err) {
+      const forwardingError = err instanceof Error ? err : new Error(String(err));
+      console.error("[helio] Upstream forwarding failed:", forwardingError.message);
+      const normalized2 = normalizeUpstreamOutcome({ requestId: id, forwardingError });
+      const errorEvent = sseEvent("message", JSON.stringify(normalized2.body));
+      writeSessionEvent(sessionId, errorEvent);
+      return c.body(null, 202);
+    }
+    const normalized = normalizeUpstreamOutcome({
+      requestId: id,
+      upstreamResponse: result.response
+    });
+    const messageEvent = sseEvent("message", JSON.stringify(normalized.body));
+    writeSessionEvent(sessionId, messageEvent);
+    return c.body(null, 202);
+  });
+  return app;
+}
+
+// src/server.ts
+var FORCE_CONNECTION_CLOSE_GRACE_MS = 1500;
+function normalizeError(error) {
+  if (error instanceof Error) return error;
+  return new Error(String(error));
+}
+function createServerHandle(server) {
+  const sockets = /* @__PURE__ */ new Set();
+  const nodeServer = server;
+  nodeServer.on("connection", (socket) => {
+    sockets.add(socket);
+    socket.on("close", () => {
+      sockets.delete(socket);
+    });
+  });
+  const forceCloseConnections = () => {
+    try {
+      nodeServer.closeIdleConnections?.();
+    } catch {
+    }
+    if (nodeServer.closeAllConnections) {
+      try {
+        nodeServer.closeAllConnections();
+      } catch {
+      }
+      return;
+    }
+    for (const socket of sockets) {
+      socket.destroy();
+    }
+  };
+  return {
+    server,
+    close: () => new Promise((resolve2, reject) => {
+      let settled = false;
+      let forceTimer;
+      const settle = (err) => {
+        if (settled) return;
+        settled = true;
+        if (forceTimer) {
+          clearTimeout(forceTimer);
+          forceTimer = void 0;
+        }
+        if (err) {
+          reject(err);
           return;
         }
-        if (typeof parsed2 !== "object" || parsed2 === null) return;
-        errorMessage = extractJsonRpcErrorMessage(parsed2);
+        resolve2();
       };
-      for (; ; ) {
-        const remainingMs = deadline - Date.now();
-        if (remainingMs <= 0) {
-          await reader.cancel().catch(() => void 0);
-          throw new Error(
-            `upstream notifications/initialized SSE response timed out after ${String(this.requestTimeoutMs)}ms`
-          );
-        }
-        let chunk;
-        try {
-          chunk = await readSseChunkWithTimeout(reader, remainingMs);
-        } catch {
-          await reader.cancel().catch(() => void 0);
-          throw new Error(
-            `upstream notifications/initialized SSE response timed out after ${String(this.requestTimeoutMs)}ms`
-          );
-        }
-        const { done, value } = chunk;
-        if (value !== void 0) {
-          scannedBytes += value.byteLength;
-          if (scannedBytes > MAX_SSE_ERROR_SCAN_BYTES) {
-            await reader.cancel().catch(() => void 0);
-            throw new Error(
-              `upstream notifications/initialized SSE response exceeded ${String(MAX_SSE_ERROR_SCAN_BYTES)} bytes`
-            );
-          }
-          state = parseSseChunk(decoder.decode(value, { stream: true }), state, onEvent);
-          if (errorMessage) {
-            await reader.cancel().catch(() => void 0);
-            return errorMessage;
-          }
-        }
-        if (done) {
-          const tail = decoder.decode();
-          if (tail) {
-            state = parseSseChunk(tail, state, onEvent);
+      try {
+        nodeServer.close((err) => {
+          if (err) {
+            settle(err);
+            return;
           }
-          return errorMessage;
-        }
+          settle();
+        });
+      } catch (error) {
+        settle(normalizeError(error));
+        return;
       }
-    }
-    const raw = await res.text();
-    if (!raw.trim()) return void 0;
-    let parsed;
-    try {
-      parsed = JSON.parse(raw);
-    } catch {
-      return void 0;
-    }
-    if (typeof parsed !== "object" || parsed === null) return void 0;
-    return extractJsonRpcErrorMessage(parsed);
-  }
-};
-async function readSseChunkWithTimeout(reader, timeoutMs) {
-  let timeoutHandle;
-  try {
-    const result = await Promise.race([
-      reader.read(),
-      new Promise((_, reject) => {
-        timeoutHandle = setTimeout(() => {
-          reject(new Error(`sse read timed out after ${String(timeoutMs)}ms`));
-        }, timeoutMs);
-      })
-    ]);
-    if (!isSseReadChunk(result)) {
-      throw new Error("upstream notifications/initialized SSE response returned invalid chunk");
-    }
-    return result;
-  } finally {
-    if (timeoutHandle) clearTimeout(timeoutHandle);
+      try {
+        nodeServer.closeIdleConnections?.();
+      } catch {
+      }
+      forceTimer = setTimeout(() => {
+        forceCloseConnections();
+      }, FORCE_CONNECTION_CLOSE_GRACE_MS);
+      forceTimer.unref();
+    })
+  };
+}
+function createApp(config, forwarder, options) {
+  const app = new Hono3();
+  const forwardHeadersAllowlist = config.upstream.forward_headers;
+  const allowedOrigins = config.listen.allowed_origins;
+  const session = compileSessionIdentity(config.session);
+  app.get("/healthz", (c) => c.json({ status: "ok" }));
+  app.route(
+    "/mcp",
+    createStreamableHttpRoute(forwarder, {
+      forwardHeadersAllowlist,
+      allowedOrigins,
+      session,
+      onHeaderMismatch: options?.onHeaderMismatch
+    })
+  );
+  app.route("/sse", createSseRoute(forwarder, { forwardHeadersAllowlist, allowedOrigins, session }));
+  if (options?.slackActionApp) {
+    app.route("/slack/actions", options.slackActionApp);
   }
+  return app;
 }
-function isSseReadChunk(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const candidate = value;
-  if (typeof candidate.done !== "boolean") return false;
-  if (candidate.value === void 0) return true;
-  return candidate.value instanceof Uint8Array;
+function startServer(app, config) {
+  const server = serve({
+    fetch: app.fetch,
+    port: config.listen.port,
+    hostname: config.listen.host
+  });
+  return createServerHandle(server);
 }
-function extractJsonRpcErrorMessage(payload) {
-  const error = payload["error"];
-  if (typeof error === "string") return error;
-  if (typeof error !== "object" || error === null) return void 0;
-  const message = error["message"];
-  if (typeof message === "string" && message.trim()) return message;
-  return "unknown JSON-RPC error";
+function startSidebandServer(app, port, host = "127.0.0.1") {
+  const server = serve({
+    fetch: app.fetch,
+    port,
+    hostname: host
+  });
+  return createServerHandle(server);
 }
-function extractNegotiatedProtocolVersion(payload) {
-  const result = payload["result"];
-  if (typeof result !== "object" || result === null) {
-    return HELIO_MCP_PROTOCOL_VERSION;
+
+// src/upstream/response.ts
+async function parseUpstreamResponse(res) {
+  const headers = {};
+  res.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+  const contentType = res.headers.get("content-type") ?? "";
+  let body;
+  if (contentType.includes("application/json")) {
+    const text = await res.text();
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+  } else {
+    body = await res.text();
   }
-  const protocolVersion = result["protocolVersion"];
-  return typeof protocolVersion === "string" && protocolVersion.trim() ? protocolVersion : HELIO_MCP_PROTOCOL_VERSION;
+  return { status: res.status, headers, body };
 }
 
 // src/upstream/streamable-http-forwarder.ts
+var JSON_RPC_METHOD_NOT_FOUND = -32601;
 var StreamableHttpForwarder = class {
   url;
   staticHeaders;
@@ -2052,7 +2901,8 @@ var StreamableHttpForwarder = class {
     this.sessions = new UpstreamSessionManager({
       url: this.url,
       staticHeaders: this.staticHeaders,
-      requestTimeoutMs: this.requestTimeoutMs
+      requestTimeoutMs: this.requestTimeoutMs,
+      protocolVersion: options.protocolVersion
     });
   }
   /** Lifecycle parity with sse/stdio. No eager connect — sessions are lazy. */
@@ -2065,15 +2915,91 @@ var StreamableHttpForwarder = class {
     return Promise.resolve();
   }
   async forward(request) {
-    if (request.method === "initialize") {
-      return this.send(
-        request,
-        request.sessionId,
-        /* protocolVersion */
-        void 0
+    const era = await this.sessions.resolveRelayEra();
+    if (era === "modern") {
+      if (request.method === "initialize") {
+        return this.synthesizeInitializeResult(request);
+      }
+      if (request.method === "notifications/initialized") {
+        return this.swallowInitializedNotification();
+      }
+      return this.send(request, {
+        sessionId: void 0,
+        protocolVersion: void 0,
+        era: "modern"
+      });
+    }
+    const result = request.method === "initialize" ? await this.send(request, {
+      sessionId: request.transportSessionId,
+      protocolVersion: void 0
+    }) : (
+      // Downstream-driven and external sessionless callers alike are
+      // transparent passthrough: forward whatever session the caller did
+      // (or did not) supply.
+      await this.send(request, {
+        sessionId: request.transportSessionId,
+        protocolVersion: HELIO_MCP_LEGACY_PROTOCOL_VERSION
+      })
+    );
+    this.inspectLegacyRelayOutcome(request, result.response);
+    return result;
+  }
+  /**
+   * The dual-era bridge (relay leg, modern era): a modern-only server
+   * answers the retired `initialize` handshake with 404/-32601, so Helio
+   * synthesizes the legacy InitializeResult locally from the upstream's own
+   * probe-time DiscoverResult. No `mcp-session-id` response header — the
+   * legacy spec permits sessionless servers, and the downstream stays
+   * sessionless. The synthesized protocolVersion is always the current
+   * legacy revision, even for a client that offered an older one.
+   */
+  synthesizeInitializeResult(request) {
+    const capture = this.sessions.getDiscoverCapture();
+    const result = {
+      protocolVersion: HELIO_MCP_LEGACY_PROTOCOL_VERSION,
+      capabilities: capture?.capabilities ?? { tools: {} },
+      // NOT copied from upstream: the 2026-07-28 DiscoverResult has no
+      // serverInfo field at all, and the bridge is Helio's own construct —
+      // matching buildInternalMeta()'s identity.
+      serverInfo: { name: "helio-proxy", version: "0" }
+    };
+    if (capture?.instructions !== void 0) {
+      result["instructions"] = capture.instructions;
+    }
+    const response = {
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { jsonrpc: "2.0", id: request.id ?? null, result }
+    };
+    return { response, durationMs: 0 };
+  }
+  /**
+   * The modern upstream removed `notifications/initialized`; answer the
+   * same minimal success envelope the SSE-notification path returns.
+   */
+  swallowInitializedNotification() {
+    const response = { status: 200, headers: {}, body: { jsonrpc: "2.0" } };
+    return { response, durationMs: 0 };
+  }
+  /**
+   * The relay-side era falsification door (issue #219): a legacy-leg relay whose answer only a
+   * modern server gives clears the cached legacy era (the manager no-ops on
+   * pins, uncached eras, and cached modern). The response still flows to the
+   * client unchanged — no in-place retry.
+   */
+  inspectLegacyRelayOutcome(request, response) {
+    const errorCode = readJsonRpcErrorCode(response.body);
+    if (errorCode !== void 0 && MCP_MODERN_ONLY_ERROR_CODES.has(errorCode)) {
+      this.sessions.clearFalsifiedLegacyEra(
+        `a relayed response carried the modern-only JSON-RPC error ${String(errorCode)}`
+      );
+      return;
+    }
+    if (request.method === "initialize" && (response.status === 404 || errorCode === JSON_RPC_METHOD_NOT_FOUND)) {
+      this.sessions.clearFalsifiedLegacyEra(
+        response.status === 404 ? "a relayed initialize was answered with HTTP 404" : "a relayed initialize was answered with JSON-RPC -32601"
       );
     }
-    return this.send(request, request.sessionId, HELIO_MCP_PROTOCOL_VERSION);
   }
   /**
    * Helio-internal execution path (startup prime / internal maintenance) that
@@ -2084,8 +3010,7 @@ var StreamableHttpForwarder = class {
     try {
       return await this.send(
         request,
-        session.sessionId,
-        session.protocolVersion,
+        session,
         /* internalManaged */
         true
       );
@@ -2095,8 +3020,7 @@ var StreamableHttpForwarder = class {
         const fresh = await this.sessions.ensureInternalSession();
         return this.send(
           request,
-          fresh.sessionId,
-          fresh.protocolVersion,
+          fresh,
           /* internalManaged */
           true
         );
@@ -2104,7 +3028,50 @@ var StreamableHttpForwarder = class {
       throw error;
     }
   }
-  async send(request, sessionId, protocolVersion, internalManaged = false) {
+  /** Drop the managed internal session AND the cached era; next internal call re-probes. */
+  resetInternalSession() {
+    this.sessions.invalidateInternalSession();
+  }
+  async send(request, session, internalManaged = false) {
+    const modern = session.era === "modern";
+    let outboundParams;
+    if (modern) {
+      if (request.params !== void 0 && !isPlainObject(request.params)) {
+        throw new Error(
+          "helio refused to forward: MCP 2026-07-28 requires the _meta mirror inside params, which cannot be attached to array or primitive params; send object params or none"
+        );
+      }
+      const params = request.params ?? {};
+      const rawMeta = params["_meta"];
+      const existingMeta = isPlainObject(rawMeta) ? rawMeta : {};
+      const internalMeta = buildInternalMeta();
+      const clientCapabilities = existingMeta["io.modelcontextprotocol/clientCapabilities"];
+      const clientInfo = existingMeta["io.modelcontextprotocol/clientInfo"];
+      outboundParams = {
+        ...params,
+        _meta: {
+          ...existingMeta,
+          [MCP_META_PROTOCOL_VERSION_KEY]: HELIO_MCP_MODERN_PROTOCOL_VERSION,
+          "io.modelcontextprotocol/clientCapabilities": clientCapabilities !== void 0 ? clientCapabilities : internalMeta["io.modelcontextprotocol/clientCapabilities"],
+          "io.modelcontextprotocol/clientInfo": clientInfo !== void 0 ? clientInfo : internalMeta["io.modelcontextprotocol/clientInfo"]
+        }
+      };
+    } else {
+      outboundParams = request.params;
+    }
+    if (modern) {
+      if (!isHeaderSafeMethod(request.method)) {
+        throw new Error(
+          "helio refused to forward: the request method cannot be carried in the Mcp-Method header that MCP 2026-07-28 requires (it contains characters outside the visible-ASCII token set), so the upstream is guaranteed to reject the request"
+        );
+      }
+      const nameValue = encodedNameValue(request.method, outboundParams);
+      if (nameValue !== void 0 && Buffer.byteLength(nameValue) > MCP_NAME_MAX_BYTES) {
+        throw new Error(
+          `helio refused to forward: params.name/uri exceeds the ${String(MCP_NAME_MAX_BYTES)}-byte Mcp-Name header cap after encoding, and MCP 2026-07-28 requires the header on this method; shorten the name or uri`
+        );
+      }
+    }
     const headers = mergeUpstreamHeaders(
       {
         "content-type": "application/json",
@@ -2113,16 +3080,26 @@ var StreamableHttpForwarder = class {
       request.headers ?? {},
       this.staticHeaders
     );
-    if (sessionId) headers["mcp-session-id"] = sessionId;
-    if (protocolVersion && headers["mcp-protocol-version"] === void 0) {
-      headers["mcp-protocol-version"] = protocolVersion;
-    }
+    if (session.sessionId) headers["mcp-session-id"] = session.sessionId;
+    if (modern) {
+      delete headers["mcp-session-id"];
+      headers["mcp-protocol-version"] = HELIO_MCP_MODERN_PROTOCOL_VERSION;
+    } else if (session.protocolVersion && headers["mcp-protocol-version"] === void 0) {
+      headers["mcp-protocol-version"] = session.protocolVersion;
+    }
+    delete headers["mcp-method"];
+    delete headers["mcp-name"];
+    Object.assign(headers, buildStandardRequestHeaders(request.method, outboundParams));
     const body = {
       jsonrpc: request.jsonrpc,
       method: request.method
     };
     if (request.id !== void 0) body["id"] = request.id;
-    if (request.params !== void 0) body["params"] = request.params;
+    if (modern) {
+      body["params"] = outboundParams;
+    } else if (request.params !== void 0) {
+      body["params"] = outboundParams;
+    }
     const start = performance.now();
     const timeoutSignal = AbortSignal.timeout(this.requestTimeoutMs);
     const requestSignal = request.signal;
@@ -2138,7 +3115,7 @@ var StreamableHttpForwarder = class {
       }
       throw describeUnreachableUpstream(error, this.url) ?? error;
     }
-    if (internalManaged && res.status === 404 && sessionId) {
+    if (internalManaged && res.status === 404 && session.sessionId) {
       await res.text().catch(() => void 0);
       throw new UpstreamSessionExpiredError();
     }
@@ -2148,6 +3125,7 @@ var StreamableHttpForwarder = class {
       res.headers.forEach((value, key) => {
         responseHeaders[key] = value;
       });
+      if (modern) delete responseHeaders["mcp-session-id"];
       if (request.id === void 0) {
         await res.body?.cancel().catch(() => void 0);
         const response3 = {
@@ -2162,6 +3140,7 @@ var StreamableHttpForwarder = class {
       return { response: response2, durationMs: performance.now() - start };
     }
     const response = await parseUpstreamResponse(res);
+    if (modern) delete response.headers["mcp-session-id"];
     return { response, durationMs: performance.now() - start };
   }
 };
@@ -2171,6 +3150,16 @@ var UpstreamSessionExpiredError = class extends Error {
     this.name = "UpstreamSessionExpiredError";
   }
 };
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readJsonRpcErrorCode(body) {
+  if (typeof body !== "object" || body === null) return void 0;
+  const error = body["error"];
+  if (typeof error !== "object" || error === null) return void 0;
+  const code = error["code"];
+  return typeof code === "number" ? code : void 0;
+}
 
 // src/mcp/pending-requests.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
@@ -2319,8 +3308,11 @@ var SseUpstreamForwarder = class {
       request.headers ?? {},
       this.staticHeaders
     );
-    if (request.sessionId) {
-      headers["mcp-session-id"] = request.sessionId;
+    delete headers["mcp-method"];
+    delete headers["mcp-name"];
+    delete headers["mcp-session-id"];
+    if (request.transportSessionId) {
+      headers["mcp-session-id"] = request.transportSessionId;
     }
     const start = performance.now();
     const signal = buildRequestSignal(request, this.requestTimeoutMs);
@@ -2637,8 +3629,14 @@ async function createForwarderFromConfig(config) {
       const http = new StreamableHttpForwarder({
         url: config.upstream.url,
         headers: config.upstream.headers,
-        requestTimeoutMs: parseDuration(config.upstream.request_timeout)
+        requestTimeoutMs: parseDuration(config.upstream.request_timeout),
+        protocolVersion: config.upstream.protocol_version
       });
+      if (config.upstream.protocol_version !== "auto") {
+        console.error(
+          `[helio] Upstream MCP protocol version pinned: ${config.upstream.protocol_version} (upstream.protocol_version)`
+        );
+      }
       await http.connect();
       return { forwarder: http, close: () => http.close() };
     }
@@ -2783,6 +3781,79 @@ function evaluatePolicy(policy, ctx) {
 // src/policy/governed-forwarder.ts
 import { randomUUID as randomUUID2 } from "crypto";
 
+// src/policy/session-gate.ts
+function isWellFormedSessionId(id) {
+  return id != null && id.trim() !== "";
+}
+function gateSession(sessionId, onUnresolved) {
+  if (isWellFormedSessionId(sessionId)) {
+    return { ok: true, session: sessionId, anonymous: false };
+  }
+  if (onUnresolved === "anonymous") {
+    return { ok: true, session: "unknown", anonymous: true };
+  }
+  return { ok: false };
+}
+function sessionLimitKey(session) {
+  return `session:${session}`;
+}
+function gateBudgetCharges(resolved, gate) {
+  const sessionEngaged = resolved.charges.some((charge) => charge.budget.key === "session") || resolved.failures.some((failure) => failure.budget.key === "session");
+  if (!gate.ok) {
+    if (sessionEngaged) return { ok: false, unresolvedEngaged: true };
+    return { ok: true, charges: resolved.charges };
+  }
+  if (gate.anonymous && sessionEngaged) warnAnonymousPoolingOnce();
+  return { ok: true, charges: resolved.charges };
+}
+function freezeGatedPlans(charges, breached) {
+  if (breached.length !== charges.length) {
+    throw new Error(
+      `freezeGatedPlans: breach markers must pair positionally with charges (${String(breached.length)} markers for ${String(charges.length)} charges)`
+    );
+  }
+  return charges.map(
+    (charge, index) => ({
+      kind: "budget",
+      budget: charge.budget,
+      bucketKey: charge.bucketKey,
+      amount: charge.amount,
+      generation: charge.generation,
+      breached: breached[index] === true
+    })
+  );
+}
+function remintDeferredCharges(frozen, actualAmount) {
+  return frozen.map((plan) => ({
+    budget: plan.budget,
+    bucketKey: plan.bucketKey,
+    amount: actualAmount ?? plan.amount,
+    generation: plan.generation
+  }));
+}
+function sessionUnresolvedControlMessage(tried) {
+  return `No session identity resolved (tried: ${tried}) \u2014 a session-keyed limit or budget requires one. See session.identity in helio.yaml.`;
+}
+function sessionRequiredForGroundingMessage(tried) {
+  return `No session identity resolved (tried: ${tried}) \u2014 rules using evidence.requires or requires need one. See session.identity in helio.yaml.`;
+}
+var unresolvedEngagementWarned = false;
+var anonymousPoolingWarned = false;
+function warnSessionUnresolvedEngagementOnce(tried) {
+  if (unresolvedEngagementWarned) return;
+  unresolvedEngagementWarned = true;
+  console.error(
+    `[helio] Warning: a session-keyed control was engaged with no resolved session identity (tried: ${tried}); session.on_unresolved: deny denies such requests (dry-run reports them). Send an identity the chain can read (e.g. the x-helio-session-id header), or set session.on_unresolved: anonymous to restore pre-0.12 shared pooling.`
+  );
+}
+function warnAnonymousPoolingOnce() {
+  if (anonymousPoolingWarned) return;
+  anonymousPoolingWarned = true;
+  console.error(
+    '[helio] Warning: session identity unresolved; session-keyed limits and budgets are pooling into the shared "unknown" bucket (session.on_unresolved: anonymous). Have callers send session identity to isolate them from each other.'
+  );
+}
+
 // src/evidence/grounding.ts
 function checkEvidence(store, sessionId, requirements) {
   if (requirements.length === 0) {
@@ -2828,7 +3899,8 @@ function checkDependencies(store, sessionId, requirements, options = {}) {
 
 // src/policy/decision-pipeline.ts
 function decide(input) {
-  const { toolName, toolArguments, sessionId, policy, environment, evidenceStore } = input;
+  const { toolName, toolArguments, policy, environment, evidenceStore } = input;
+  const sessionId = isWellFormedSessionId(input.sessionId) ? input.sessionId : void 0;
   const annotations = input.baselineAnnotations;
   const driftEvent = input.driftEvent;
   const driftMode = policy.onToolDrift ?? "block";
@@ -2887,7 +3959,9 @@ function decide(input) {
     decision = {
       action: "deny",
       matchedRule: decision.matchedRule,
-      reason: "Mcp-Session-Id is required for evidence/dependency-gated policy rules"
+      reason: sessionRequiredForGroundingMessage(
+        input.sessionStrategySummary ?? "the configured session.identity chain"
+      )
     };
   }
   if (decision.action !== "deny" && evidenceStore && sessionId && decision.matchedRule) {
@@ -3338,6 +4412,17 @@ function buildToolDriftFeedback(drift, action) {
     retry_allowed: false
   };
 }
+function buildSessionUnresolvedFeedback(decision, control, tried) {
+  return {
+    blocked: true,
+    reason: "session_unresolved",
+    ...ruleInfo(decision.matchedRule),
+    control,
+    tried,
+    suggestion: `No session identity resolved (tried: ${tried}). Send an identity the chain can read \u2014 for example set the x-helio-session-id header once per agent run \u2014 or set session.on_unresolved: anonymous to restore shared pooling.`,
+    retry_allowed: true
+  };
+}
 function buildSpendLimitedFeedback(decision, result, currency) {
   const info = ruleInfo(decision.matchedRule);
   const windowSeconds = Math.round(result.windowMs / 1e3);
@@ -3795,6 +4880,7 @@ var GovernedForwarder = class {
   inner;
   policy;
   environment;
+  session;
   auditWriter;
   evidenceStore;
   approvalRouter;
@@ -3814,6 +4900,7 @@ var GovernedForwarder = class {
     this.rateLimiter = options?.rateLimiter;
     this.spendLimiter = options?.spendLimiter;
     this.budgetEngine = options?.budgetEngine;
+    this.session = options?.session ?? DEFAULT_SESSION_IDENTITY;
     if (this.evidenceStore) {
       this.evidenceStore.setAllowedEvidenceKeys(collectAllowedEvidenceKeys(policy));
     }
@@ -3887,6 +4974,7 @@ var GovernedForwarder = class {
     try {
       const result = typeof internal.forwardInternal === "function" ? await internal.forwardInternal(syntheticToolsList) : await this.inner.forward(syntheticToolsList);
       if (result.response.status >= 400) {
+        internal.resetInternalSession?.();
         return {
           success: false,
           toolsCached: this.annotationCache.size,
@@ -3895,6 +4983,7 @@ var GovernedForwarder = class {
       }
       const update = this.applyToolDefinitionUpdate(result.response.body, void 0);
       if (!update.updated) {
+        internal.resetInternalSession?.();
         return {
           success: false,
           toolsCached: this.annotationCache.size,
@@ -3903,6 +4992,7 @@ var GovernedForwarder = class {
       }
       return { success: true, toolsCached: this.annotationCache.size };
     } catch (error) {
+      internal.resetInternalSession?.();
       return {
         success: false,
         toolsCached: this.annotationCache.size,
@@ -3916,17 +5006,42 @@ var GovernedForwarder = class {
     }
     const result = await this.inner.forward(request);
     if (request.method === "tools/list") {
-      this.applyToolDefinitionUpdate(result.response.body, request.sessionId);
+      this.applyToolDefinitionUpdate(result.response.body, request.session);
+      this.clampCacheHints(result.response.body);
     }
     return result;
   }
+  /**
+   * Clamp an over-long `result.ttlMs` on a `tools/list` response to
+   * `policies.tool_revalidation.max_advertised_ttl` (issue #221, D7).
+   *
+   * Downward-only: a `ttlMs` at or below the cap is left untouched, and a
+   * response with no `ttlMs` never gains one — Helio does not manufacture a
+   * cache hint the upstream never advertised. Non-numeric values are left
+   * alone rather than coerced. `cacheScope` passes through untouched: Helio
+   * baselines and vouches for tool *definitions* only, and its own
+   * `tools/list` view is not caller-varying, so it has no basis to alter a
+   * scope hint the upstream set. No-op when tool revalidation is disabled
+   * (including hand-built `CompiledPolicy` fixtures that omit the field).
+   */
+  clampCacheHints(responseBody) {
+    const rv = this.policy.toolRevalidation;
+    if (!rv?.enabled) return;
+    if (typeof responseBody !== "object" || responseBody === null) return;
+    const result = responseBody["result"];
+    if (typeof result !== "object" || result === null) return;
+    const r = result;
+    if (typeof r["ttlMs"] === "number" && r["ttlMs"] > rv.maxAdvertisedTtlMs) {
+      r["ttlMs"] = rv.maxAdvertisedTtlMs;
+    }
+  }
   /**
    * Apply a tools/list response to the definition cache and surface any
    * drift: console warning + immediate audit record per event. Single entry
    * point for both runtime tools/list responses and startup priming, so the
    * cache is updated exactly once per response.
    */
-  applyToolDefinitionUpdate(responseBody, sessionId) {
+  applyToolDefinitionUpdate(responseBody, session) {
     const update = this.annotationCache.update(responseBody);
     if (!update.updated) return update;
     for (const drift of update.drifted) {
@@ -3934,22 +5049,23 @@ var GovernedForwarder = class {
       console.error(
         `[helio] Tool definition drift detected: "${drift.toolName}" changed (${aspects}) after baseline \u2014 calls governed by policies.on_tool_drift (${this.policy.onToolDrift ?? "block"})`
       );
-      this.writeDriftAuditRecord(drift, sessionId, "tool_drift");
+      this.writeDriftAuditRecord(drift, session, "tool_drift");
     }
     for (const toolName of update.reverted) {
       console.error(
         `[helio] Tool definition drift cleared: "${toolName}" returned to its baseline definition`
       );
-      this.writeDriftAuditRecord({ toolName, changes: [] }, sessionId, "tool_drift_reverted");
+      this.writeDriftAuditRecord({ toolName, changes: [] }, session, "tool_drift_reverted");
     }
     return update;
   }
   /** Write an immediate audit record for a drift event (not a tool call). */
-  writeDriftAuditRecord(drift, sessionId, decision) {
+  writeDriftAuditRecord(drift, session, decision) {
     if (!this.auditWriter) return;
     this.auditWriter.pushImmediate({
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      session_id: sessionId ?? null,
+      session_id: session?.id ?? null,
+      session_source: session?.source ?? null,
       agent_id: null,
       environment: this.environment ?? null,
       tool_name: drift.toolName,
@@ -3972,7 +5088,9 @@ var GovernedForwarder = class {
       dry_run: false,
       record_kind: "drift_event",
       origin: "mcp",
-      metadata: null
+      metadata: null,
+      // Drift is a cache event, not a request: no protocol claim exists.
+      protocol_version: null
     });
   }
   async handleToolsCall(original) {
@@ -4009,7 +5127,8 @@ var GovernedForwarder = class {
     } = decide({
       toolName,
       toolArguments,
-      sessionId: request.sessionId,
+      sessionId: request.session?.id,
+      sessionStrategySummary: this.session.strategySummary,
       policy: this.policy,
       environment: this.environment,
       evidenceStore: this.evidenceStore,
@@ -4102,9 +5221,10 @@ var GovernedForwarder = class {
       });
     }
     try {
-      if (forwarded && !isDryRun && this.evidenceStore && request.sessionId && toolName) {
+      const dependencySessionId = request.session?.id;
+      if (forwarded && !isDryRun && this.evidenceStore && isWellFormedSessionId(dependencySessionId) && toolName) {
         const succeeded = !hasJsonRpcError(result);
-        this.evidenceStore.recordToolCall(request.sessionId, toolName, succeeded);
+        this.evidenceStore.recordToolCall(dependencySessionId, toolName, succeeded);
       }
     } catch (err) {
       console.error("[helio] dependency tracking failed after forward:", err);
@@ -4125,6 +5245,7 @@ var GovernedForwarder = class {
       evidenceResult,
       dependencyResult,
       evidenceBlocked,
+      sessionBlocked,
       approvalOutcome,
       approvalContext,
       rateLimitResult,
@@ -4155,7 +5276,7 @@ var GovernedForwarder = class {
         tool_name: toolName,
         tool_input: toolArguments ?? {},
         matched_rule: decision.matchedRule,
-        session_id: request.sessionId ?? null,
+        session_id: request.session?.id ?? null,
         breached_budgets: gate.breachContexts,
         approval: gate.approval
       },
@@ -4298,15 +5419,25 @@ var GovernedForwarder = class {
   gateBudgets(request, decision, toolName, toolArguments) {
     const engine = this.budgetEngine;
     if (!engine) return { kind: "proceed" };
+    const sessionGate = gateSession(request.session?.id, this.session.onUnresolved);
     const { charges, failures } = engine.resolveCharges({
       toolName,
       toolArguments,
-      sessionId: request.sessionId ?? null,
+      sessionId: sessionGate.ok ? sessionGate.session : null,
       senderId: null
       // adapter context; absent on the MCP path
     });
     if (charges.length === 0 && failures.length === 0) return { kind: "proceed" };
-    const peek = charges.length > 0 ? engine.peekAll(charges) : { allowed: true, entries: [] };
+    const gated = gateBudgetCharges({ charges, failures }, sessionGate);
+    if (!gated.ok) {
+      warnSessionUnresolvedEngagementOnce(this.session.strategySummary);
+      return {
+        kind: "blocked",
+        result: this.makeSessionUnresolvedResult(request, decision, "budget"),
+        chain: []
+      };
+    }
+    const peek = charges.length > 0 ? engine.peekAll(gated.charges) : { allowed: true, entries: [] };
     const breaches = peek.entries.filter((entry) => !entry.allowed);
     const anyHardDeny = failures.length > 0 || breaches.some((entry) => entry.budget.onExceed === "deny");
     if (breaches.length > 0) engine.reportBreaches(breaches);
@@ -4339,7 +5470,7 @@ var GovernedForwarder = class {
     const peekBlockByName = new Map(
       peek.entries.map((entry) => [entry.budget.name, budgetChainBlock(entry)])
     );
-    const commit = (auditRecordId, kinds) => engine.recordAll(charges, {
+    const commit = (auditRecordId, kinds) => engine.recordAll(gated.charges, {
       kind: "spend",
       ...kinds ? { kinds } : {},
       auditRecordId,
@@ -4415,7 +5546,8 @@ var GovernedForwarder = class {
       const toolInput = { raw_params: params ?? null };
       this.auditWriter.pushImmediate({
         timestamp,
-        session_id: request.sessionId ?? null,
+        session_id: request.session?.id ?? null,
+        session_source: request.session?.source ?? null,
         agent_id: null,
         environment: this.environment ?? null,
         tool_name: "<nameless>",
@@ -4438,7 +5570,8 @@ var GovernedForwarder = class {
         dry_run: false,
         record_kind: "tool_call",
         origin: "mcp",
-        metadata: null
+        metadata: null,
+        protocol_version: request.protocolVersion ?? null
       });
     }
     return result;
@@ -4451,7 +5584,7 @@ var GovernedForwarder = class {
         tool_name: toolName,
         tool_input: toolArguments ?? {},
         matched_rule: decision.matchedRule,
-        session_id: request.sessionId ?? null
+        session_id: request.session?.id ?? null
       },
       request.signal
     );
@@ -4547,7 +5680,20 @@ var GovernedForwarder = class {
         rateLimitResult: { allowed: false, current: 0, limit: 0, windowMs: 0, resetAtMs: 0 }
       };
     }
-    const key = this.buildLimitKey(limits.key, toolName, request);
+    let key;
+    if (limits.key === "session") {
+      const sessionKey = this.gateSessionLimitKey(request);
+      if (sessionKey === null) {
+        return {
+          proceed: false,
+          result: this.makeSessionUnresolvedResult(request, decision, "rate_limit"),
+          approvalWaitMs: 0
+        };
+      }
+      key = sessionKey;
+    } else {
+      key = this.buildLimitKey(limits.key, toolName);
+    }
     const params = { key, maxCalls: limits.maxCalls, windowMs: limits.windowMs };
     const rateLimitResult = limiter.peek(params);
     if (!rateLimitResult.allowed) {
@@ -4585,7 +5731,21 @@ var GovernedForwarder = class {
         spendLimitResult: { allowed: false, currentSpend: 0, limit: 0, windowMs: 0, resetAtMs: 0 }
       };
     }
-    const key = this.buildSpendLimitKey(maxSpend.key, toolName, request, decision.matchedRule.index);
+    let baseKey;
+    if (maxSpend.key === "session") {
+      const sessionKey = this.gateSessionLimitKey(request);
+      if (sessionKey === null) {
+        return {
+          proceed: false,
+          result: this.makeSessionUnresolvedResult(request, decision, "spend_limit"),
+          approvalWaitMs: 0
+        };
+      }
+      baseKey = sessionKey;
+    } else {
+      baseKey = this.buildLimitKey(maxSpend.key, toolName);
+    }
+    const key = spendBucketKey(baseKey, decision.matchedRule.index);
     const rawAmount = resolvePath(maxSpend.field, toolArguments ?? {});
     if (typeof rawAmount !== "number") {
       console.error(
@@ -4649,6 +5809,7 @@ var GovernedForwarder = class {
     const evidenceSatisfied = !evidenceBlocked;
     let wouldForward = false;
     let limitsOk = true;
+    let sessionUnresolved = false;
     if (!evidenceBlocked) {
       switch (decision.action) {
         case "allow":
@@ -4656,14 +5817,21 @@ var GovernedForwarder = class {
           break;
         case "rate_limit":
           if (this.rateLimiter && decision.matchedRule?.limits?.maxCalls && decision.matchedRule.limits.windowMs) {
-            const key = this.buildLimitKey(decision.matchedRule.limits.key, toolName, request);
-            const peekResult = this.rateLimiter.peek({
-              key,
-              maxCalls: decision.matchedRule.limits.maxCalls,
-              windowMs: decision.matchedRule.limits.windowMs
-            });
-            wouldForward = peekResult.allowed;
-            limitsOk = peekResult.allowed;
+            const limits = decision.matchedRule.limits;
+            const key = limits.key === "session" ? this.gateSessionLimitKey(request) : this.buildLimitKey(limits.key, toolName);
+            if (key === null) {
+              wouldForward = false;
+              limitsOk = false;
+              sessionUnresolved = true;
+            } else {
+              const peekResult = this.rateLimiter.peek({
+                key,
+                maxCalls: decision.matchedRule.limits.maxCalls,
+                windowMs: decision.matchedRule.limits.windowMs
+              });
+              wouldForward = peekResult.allowed;
+              limitsOk = peekResult.allowed;
+            }
           }
           break;
         case "spend_limit":
@@ -4683,20 +5851,21 @@ var GovernedForwarder = class {
               wouldForward = false;
               limitsOk = false;
             } else {
-              const key = this.buildSpendLimitKey(
-                maxSpend.key,
-                toolName,
-                request,
-                decision.matchedRule.index
-              );
-              const peekResult = this.spendLimiter.peek({
-                key,
-                amount: rawAmount,
-                limit: maxSpend.limit,
-                windowMs: maxSpend.windowMs
-              });
-              wouldForward = peekResult.allowed;
-              limitsOk = peekResult.allowed;
+              const baseKey = maxSpend.key === "session" ? this.gateSessionLimitKey(request) : this.buildLimitKey(maxSpend.key, toolName);
+              if (baseKey === null) {
+                wouldForward = false;
+                limitsOk = false;
+                sessionUnresolved = true;
+              } else {
+                const peekResult = this.spendLimiter.peek({
+                  key: spendBucketKey(baseKey, decision.matchedRule.index),
+                  amount: rawAmount,
+                  limit: maxSpend.limit,
+                  windowMs: maxSpend.windowMs
+                });
+                wouldForward = peekResult.allowed;
+                limitsOk = peekResult.allowed;
+              }
             }
           }
           break;
@@ -4704,30 +5873,39 @@ var GovernedForwarder = class {
     }
     let budgets;
     if (wouldForward && this.budgetEngine) {
+      const sessionGate = gateSession(request.session?.id, this.session.onUnresolved);
       const { charges, failures } = this.budgetEngine.resolveCharges({
         toolName,
         toolArguments,
-        sessionId: request.sessionId ?? null,
+        sessionId: sessionGate.ok ? sessionGate.session : null,
         senderId: null
       });
       if (failures.length > 0 || charges.length > 0) {
-        const peek = charges.length > 0 ? this.budgetEngine.peekAll(charges) : { allowed: true, entries: [] };
-        const ok = failures.length === 0 && peek.allowed;
-        wouldForward &&= ok;
-        limitsOk &&= ok;
-        budgets = [
-          ...peek.entries.map((entry) => budgetChainBlock(entry)),
-          ...failures.map((failure) => ({
-            name: failure.budget.name,
-            bucket_key: failure.bucketKey,
-            allowed: false,
-            reason: failure.reason,
-            spent: failure.spent,
-            limit: failure.budget.limit,
-            remaining: failure.remaining,
-            currency: failure.budget.currency
-          }))
-        ];
+        const gated = gateBudgetCharges({ charges, failures }, sessionGate);
+        if (!gated.ok) {
+          warnSessionUnresolvedEngagementOnce(this.session.strategySummary);
+          wouldForward = false;
+          limitsOk = false;
+          sessionUnresolved = true;
+        } else {
+          const peek = charges.length > 0 ? this.budgetEngine.peekAll(gated.charges) : { allowed: true, entries: [] };
+          const ok = failures.length === 0 && peek.allowed;
+          wouldForward &&= ok;
+          limitsOk &&= ok;
+          budgets = [
+            ...peek.entries.map((entry) => budgetChainBlock(entry)),
+            ...failures.map((failure) => ({
+              name: failure.budget.name,
+              bucket_key: failure.bucketKey,
+              allowed: false,
+              reason: failure.reason,
+              spent: failure.spent,
+              limit: failure.budget.limit,
+              remaining: failure.remaining,
+              currency: failure.budget.currency
+            }))
+          ];
+        }
       }
     }
     return this.makeDryRunResult(
@@ -4736,14 +5914,18 @@ var GovernedForwarder = class {
       wouldForward,
       evidenceSatisfied,
       limitsOk,
-      budgets
+      budgets,
+      sessionUnresolved
     );
   }
-  /** Construct a limit bucket key based on the configured key type. */
-  buildLimitKey(keyType, toolName, request) {
+  /**
+   * Construct a non-session limit bucket key. Session keys are deliberately
+   * NOT built here: they come only from the gate module's `sessionLimitKey`,
+   * whose `GatedSession` parameter makes skipping the identity gate a
+   * compile error (issue #218) — call sites branch on `key === 'session'`.
+   */
+  buildLimitKey(keyType, toolName) {
     switch (keyType) {
-      case "session":
-        return `session:${request.sessionId ?? "unknown"}`;
       case "agent":
         if (!this.agentKeyWarned) {
           this.agentKeyWarned = true;
@@ -4766,14 +5948,29 @@ var GovernedForwarder = class {
     }
   }
   /**
-   * Construct a spend bucket key via the shared {@link spendBucketKey}
-   * composer — see its doc for why spend buckets are rule-discriminated.
-   * Rate buckets keep the undiscriminated keys.
+   * Gate a session-keyed limit at its key-build site (issue #218). Returns
+   * the bucket key, or null when identity is unresolved under deny mode —
+   * the caller denies (enforce) or reports the marker (dry-run).
    */
-  buildSpendLimitKey(keyType, toolName, request, ruleIndex) {
-    return spendBucketKey(this.buildLimitKey(keyType, toolName, request), ruleIndex);
+  gateSessionLimitKey(request) {
+    const gate = gateSession(request.session?.id, this.session.onUnresolved);
+    if (!gate.ok) {
+      warnSessionUnresolvedEngagementOnce(this.session.strategySummary);
+      return null;
+    }
+    if (gate.anonymous) warnAnonymousPoolingOnce();
+    return sessionLimitKey(gate.session);
+  }
+  makeSessionUnresolvedResult(request, decision, control) {
+    const feedback = buildSessionUnresolvedFeedback(decision, control, this.session.strategySummary);
+    return makeErrorResult(
+      request,
+      POLICY_DENIED,
+      sessionUnresolvedControlMessage(this.session.strategySummary),
+      { ...feedback }
+    );
   }
-  writeAuditRecord(request, auditRecordId, timestamp, toolName, toolArguments, decision, result, totalDurationMs, approvalWaitMs, flaggedDestructive, forwarded, evidenceResult, dependencyResult, evidenceBlocked, approvalOutcome, approvalContext, rateLimitResult, spendLimitResult, budgetsChain, budgetApproval, isDryRun, forwardingError, drift) {
+  writeAuditRecord(request, auditRecordId, timestamp, toolName, toolArguments, decision, result, totalDurationMs, approvalWaitMs, flaggedDestructive, forwarded, evidenceResult, dependencyResult, evidenceBlocked, sessionBlocked, approvalOutcome, approvalContext, rateLimitResult, spendLimitResult, budgetsChain, budgetApproval, isDryRun, forwardingError, drift) {
     if (!this.auditWriter) return;
     const actuallyForwarded = forwarded && !isDryRun;
     const hadForwardingError = forwardingError !== void 0;
@@ -4866,9 +6063,16 @@ var GovernedForwarder = class {
       };
     }
     const blockReason = extractBlockReason(result);
+    if (sessionBlocked || blockReason === "session_unresolved") {
+      evidenceChain = {
+        ...evidenceChain ?? {},
+        session: { unresolved: true, tried: this.session.strategySummary }
+      };
+    }
     const record = {
       timestamp,
-      session_id: request.sessionId ?? null,
+      session_id: request.session?.id ?? null,
+      session_source: request.session?.source ?? null,
       agent_id: null,
       environment: this.environment ?? null,
       tool_name: toolName,
@@ -4894,7 +6098,8 @@ var GovernedForwarder = class {
       dry_run: isDryRun ?? false,
       record_kind: "tool_call",
       origin: "mcp",
-      metadata: null
+      metadata: null,
+      protocol_version: request.protocolVersion ?? null
     };
     const isEnforcementDecision = !isDryRun && (!forwarded || approvalOutcome !== void 0 || budgetApproval !== void 0);
     if (isEnforcementDecision) {
@@ -4937,7 +6142,7 @@ var GovernedForwarder = class {
       unsupported: true
     });
   }
-  makeDryRunResult(request, decision, wouldForward, evidenceSatisfied, limitsOk, budgets) {
+  makeDryRunResult(request, decision, wouldForward, evidenceSatisfied, limitsOk, budgets, sessionUnresolved) {
     const payload = {
       dry_run: true,
       would_forward: wouldForward,
@@ -4945,13 +6150,19 @@ var GovernedForwarder = class {
       matched_rule: decision.matchedRule?.name ?? null,
       evidence_satisfied: evidenceSatisfied,
       limits_ok: limitsOk,
-      ...budgets ? { budgets } : {}
+      ...budgets ? { budgets } : {},
+      ...sessionUnresolved ? { session_unresolved: true } : {}
     };
     const body = {
       jsonrpc: "2.0",
       id: request.id ?? null,
       result: {
-        content: [{ type: "text", text: JSON.stringify(payload) }]
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        // `resultType` is REQUIRED on every 2026-07-28 result; earlier
+        // revisions never defined it, so the field rides on the client's
+        // validated wire claim — the same tokenizer the #226 door uses for
+        // its tier decision, keeping the two verdicts in agreement.
+        ...isModernProtocolClaim(request.protocolVersion) ? { resultType: "complete" } : {}
       }
     };
     const response = {
@@ -4974,15 +6185,10 @@ var GovernedForwarder = class {
   }
   makeSessionRequiredBlockResult(request, decision) {
     const feedback = buildPolicyDeniedFeedback(decision);
-    return makeErrorResult(
-      request,
-      POLICY_DENIED,
-      "Mcp-Session-Id is required for evidence/dependency-gated policy rules",
-      {
-        ...feedback,
-        retry_allowed: true
-      }
-    );
+    return makeErrorResult(request, POLICY_DENIED, decision.reason, {
+      ...feedback,
+      retry_allowed: true
+    });
   }
   makeClientDisconnectedBlockResult(request, decision) {
     const feedback = buildClientDisconnectedFeedback(decision);
@@ -5315,6 +6521,127 @@ var RateLimiter = class {
   }
 };
 
+// src/policy/annotation-prime-loop.ts
+var ANNOTATION_PRIME_INITIAL_WAIT_MS = 1500;
+var ANNOTATION_PRIME_RETRY_BASE_MS = 1e3;
+var ANNOTATION_PRIME_RETRY_MAX_MS = 3e4;
+var ANNOTATION_PRIME_RETRY_JITTER_MS = 250;
+function computePrimeRetryDelayMs(attempt) {
+  const exponent = Math.max(0, attempt - 1);
+  const baseDelay = Math.min(
+    ANNOTATION_PRIME_RETRY_MAX_MS,
+    ANNOTATION_PRIME_RETRY_BASE_MS * 2 ** exponent
+  );
+  const jitter = Math.floor(Math.random() * ANNOTATION_PRIME_RETRY_JITTER_MS);
+  return Math.min(ANNOTATION_PRIME_RETRY_MAX_MS, baseDelay + jitter);
+}
+async function startAnnotationPrimeLoop(forwarder, revalidation) {
+  let stopped = false;
+  let primed = false;
+  let retryAttempt = 0;
+  let retryTimer;
+  let current = revalidation;
+  let revalidateTimer;
+  let revalidateEpoch = 0;
+  const clearRetryTimer = () => {
+    if (!retryTimer) return;
+    clearTimeout(retryTimer);
+    retryTimer = void 0;
+  };
+  const clearRevalidateTimer = () => {
+    if (!revalidateTimer) return;
+    clearTimeout(revalidateTimer);
+    revalidateTimer = void 0;
+  };
+  const scheduleRevalidation = () => {
+    const rv = current;
+    if (stopped || !primed || !rv?.enabled || revalidateTimer) return;
+    const epoch = revalidateEpoch;
+    revalidateTimer = setTimeout(() => {
+      revalidateTimer = void 0;
+      void forwarder.primeAnnotationCache().then((result) => {
+        if (epoch !== revalidateEpoch) return;
+        if (!result.success) {
+          console.error(
+            `[helio] Tool revalidation failed: ${result.reason ?? "unknown reason"} \u2014 keeping the last baselines; next attempt in ${String(rv.intervalMs)}ms`
+          );
+        }
+        scheduleRevalidation();
+      });
+    }, rv.intervalMs);
+    revalidateTimer.unref();
+  };
+  const stop = () => {
+    stopped = true;
+    revalidateEpoch += 1;
+    clearRetryTimer();
+    clearRevalidateTimer();
+  };
+  const reconfigure = (next) => {
+    current = next;
+    revalidateEpoch += 1;
+    clearRevalidateTimer();
+    scheduleRevalidation();
+  };
+  const scheduleRetry = () => {
+    if (stopped || primed || retryTimer) return;
+    retryAttempt += 1;
+    const delayMs = computePrimeRetryDelayMs(retryAttempt);
+    console.error(
+      `[helio] Annotation cache prime retry ${String(retryAttempt)} scheduled in ${String(delayMs)}ms`
+    );
+    retryTimer = setTimeout(() => {
+      retryTimer = void 0;
+      void runPrimeAttempt("retry");
+    }, delayMs);
+    retryTimer.unref();
+  };
+  const handlePrimeResult = (phase, result) => {
+    if (stopped || primed) return;
+    if (result.success) {
+      primed = true;
+      clearRetryTimer();
+      const prefix = phase === "initial" ? "[helio] Annotation cache primed" : `[helio] Annotation cache primed after retry ${String(retryAttempt)}`;
+      console.error(
+        `${prefix}: ${String(result.toolsCached)} tool definitions baselined for drift detection (baselines are per-process; a restart re-baselines \u2014 review tool_drift audit records before restarting)`
+      );
+      scheduleRevalidation();
+      return;
+    }
+    const reason = result.reason ?? "unknown reason";
+    if (phase === "initial") {
+      console.error(
+        `[helio] Annotation cache priming failed: ${reason} \u2014 undocumented tools will be denied (fail-closed) until priming succeeds`
+      );
+    } else {
+      console.error(
+        `[helio] Annotation cache prime retry ${String(retryAttempt)} failed: ${reason} \u2014 still fail-closed`
+      );
+    }
+    scheduleRetry();
+  };
+  const runPrimeAttempt = async (phase) => {
+    const result = await forwarder.primeAnnotationCache();
+    handlePrimeResult(phase, result);
+  };
+  const initialAttempt = runPrimeAttempt("initial");
+  const initialOutcome = await Promise.race([
+    initialAttempt.then(() => "completed"),
+    new Promise((resolve2) => {
+      setTimeout(() => {
+        resolve2("timeout");
+      }, ANNOTATION_PRIME_INITIAL_WAIT_MS).unref();
+    })
+  ]);
+  if (initialOutcome === "timeout") {
+    console.error(
+      `[helio] Annotation cache priming did not complete within ${String(ANNOTATION_PRIME_INITIAL_WAIT_MS)}ms; continuing startup fail-closed and retrying in background`
+    );
+    scheduleRetry();
+  }
+  return { stop, reconfigure };
+}
+
 // src/audit/store.ts
 import Database from "better-sqlite3";
 import { randomUUID as randomUUID3 } from "crypto";
@@ -5389,6 +6716,7 @@ CREATE TABLE IF NOT EXISTS audit_records (
   id                TEXT PRIMARY KEY,
   timestamp         TEXT NOT NULL,
   session_id        TEXT,
+  session_source    TEXT,
   agent_id          TEXT,
   environment       TEXT,
   tool_name         TEXT NOT NULL,
@@ -5412,6 +6740,7 @@ CREATE TABLE IF NOT EXISTS audit_records (
   record_kind       TEXT NOT NULL DEFAULT 'tool_call',
   origin            TEXT NOT NULL DEFAULT 'mcp',
   metadata          TEXT,
+  protocol_version  TEXT,
   created_at        TEXT NOT NULL
 );
 `;
@@ -5427,19 +6756,19 @@ CREATE INDEX IF NOT EXISTS idx_audit_origin          ON audit_records (origin);
 `;
 var INSERT_SQL = `
 INSERT INTO audit_records (
-  id, timestamp, session_id, agent_id, environment, tool_name, tool_input,
+  id, timestamp, session_id, session_source, agent_id, environment, tool_name, tool_input,
   policy_decision, block_reason, matched_rule, matched_rule_index, evidence_chain, approval_status,
   approved_by, upstream_response, upstream_error, upstream_latency_ms,
   upstream_http_status,
   total_duration_ms, approval_wait_ms, proxy_compute_ms,
-  flagged_destructive, dry_run, record_kind, origin, metadata, created_at
+  flagged_destructive, dry_run, record_kind, origin, metadata, protocol_version, created_at
 ) VALUES (
-  @id, @timestamp, @session_id, @agent_id, @environment, @tool_name, @tool_input,
+  @id, @timestamp, @session_id, @session_source, @agent_id, @environment, @tool_name, @tool_input,
   @policy_decision, @block_reason, @matched_rule, @matched_rule_index, @evidence_chain, @approval_status,
   @approved_by, @upstream_response, @upstream_error, @upstream_latency_ms,
   @upstream_http_status,
   @total_duration_ms, @approval_wait_ms, @proxy_compute_ms,
-  @flagged_destructive, @dry_run, @record_kind, @origin, @metadata, @created_at
+  @flagged_destructive, @dry_run, @record_kind, @origin, @metadata, @protocol_version, @created_at
 )
 `;
 var REQUIRED_AUDIT_COLUMNS = [
@@ -5452,13 +6781,20 @@ var REQUIRED_AUDIT_COLUMNS = [
   "upstream_http_status",
   "record_kind",
   "origin",
-  "metadata"
+  "metadata",
+  // Deliberately listed (issue #218): pre-0.12 local DBs fail fast with the
+  // documented delete-these-files message — the pre-1.0 clean-break policy.
+  "session_source",
+  // Same clean break, same unreleased cycle (issue #219): released users see
+  // ONE break, at v0.12.0.
+  "protocol_version"
 ];
 function deserializeRow(row) {
   return {
     id: row.id,
     timestamp: row.timestamp,
     session_id: row.session_id,
+    session_source: row.session_source,
     agent_id: row.agent_id,
     environment: row.environment,
     tool_name: row.tool_name,
@@ -5482,6 +6818,7 @@ function deserializeRow(row) {
     record_kind: row.record_kind,
     origin: row.origin,
     metadata: row.metadata ? JSON.parse(row.metadata) : null,
+    protocol_version: row.protocol_version,
     created_at: row.created_at
   };
 }
@@ -5665,6 +7002,7 @@ var AuditStore = class {
       id: resolvedId,
       timestamp: record.timestamp,
       session_id: record.session_id,
+      session_source: record.session_source,
       agent_id: record.agent_id,
       environment: record.environment,
       tool_name: record.tool_name,
@@ -5688,6 +7026,7 @@ var AuditStore = class {
       record_kind: record.record_kind,
       origin: record.origin,
       metadata: record.metadata ? JSON.stringify(record.metadata) : null,
+      protocol_version: record.protocol_version,
       created_at: now
     });
     return resolvedId;
@@ -5956,6 +7295,48 @@ var AuditWriter = class {
   }
 };
 
+// src/audit/header-mismatch.ts
+function buildHeaderMismatchAuditRecord(rejection, environment) {
+  return {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    session_id: rejection.session?.id ?? null,
+    session_source: rejection.session?.source ?? null,
+    agent_id: null,
+    environment: environment ?? null,
+    tool_name: rejection.bodyName ?? "<header_mismatch>",
+    // Wrap parity with the nameless precedent: the wire params always nest
+    // under `raw_params`, so a wrapped scalar can never be confused with an
+    // object that happens to contain a `raw_params` key. Headers are the
+    // present markers only, verbatim as received.
+    tool_input: {
+      raw_params: rejection.params ?? null,
+      body_method: rejection.method,
+      mismatch_reason: rejection.reason,
+      headers: { ...rejection.headers }
+    },
+    policy_decision: "rejected",
+    block_reason: "header_mismatch",
+    matched_rule: null,
+    matched_rule_index: null,
+    evidence_chain: null,
+    approval_status: null,
+    approved_by: null,
+    upstream_response: null,
+    upstream_error: null,
+    upstream_http_status: null,
+    upstream_latency_ms: null,
+    total_duration_ms: rejection.durationMs,
+    approval_wait_ms: 0,
+    proxy_compute_ms: rejection.durationMs,
+    flagged_destructive: false,
+    dry_run: false,
+    record_kind: "tool_call",
+    origin: "mcp",
+    metadata: null,
+    protocol_version: rejection.protocolVersion ?? null
+  };
+}
+
 // src/evidence/store.ts
 var EvidenceStore = class _EvidenceStore {
   static EVIDENCE_ALLOWLIST_PREVIEW_LIMIT = 20;
@@ -6438,15 +7819,18 @@ function asStatus(status) {
 
 // src/evidence/api.ts
 var SIDEBAND_BODY_LIMIT_BYTES = 1 * 1024 * 1024;
+var sessionIdSchema = z5.string().min(1).refine((value) => value.trim() !== "", {
+  message: "session_id must not be whitespace-only"
+});
 var postEvidenceBody = z5.object({
-  session_id: z5.string().min(1),
+  session_id: sessionIdSchema,
   tool_name: z5.string().min(1),
   evidence_key: z5.string().min(1),
   evidence_data: z5.unknown().refine((v) => v !== void 0, { message: "Required" }),
   ttl_seconds: z5.number().int().positive().optional()
 });
 var postContextBody = z5.object({
-  session_id: z5.string().min(1),
+  session_id: sessionIdSchema,
   key: z5.string().min(1),
   value: z5.unknown().refine((v) => v !== void 0, { message: "Required" })
 });
@@ -6576,6 +7960,7 @@ var SWEEP_INTERVAL_MS2 = 3e4;
 var GovernanceService = class {
   policy;
   environment;
+  session;
   evidenceStore;
   approvalRouter;
   rateLimiter;
@@ -6609,6 +7994,7 @@ var GovernanceService = class {
   constructor(options) {
     this.policy = options.policy;
     this.environment = options.environment;
+    this.session = options.session ?? DEFAULT_SESSION_IDENTITY;
     this.evidenceStore = options.evidenceStore;
     this.approvalRouter = options.approvalRouter;
     this.rateLimiter = options.rateLimiter;
@@ -6643,6 +8029,7 @@ var GovernanceService = class {
     if (reserved) {
       return { status: 400, body: { error: "reserved_metadata_key", key: reserved } };
     }
+    const sessionId = isWellFormedSessionId(req.session_id) ? req.session_id : null;
     const inputBytes = byteLength(req.arguments ?? {});
     if (inputBytes > MAX_TOOL_INPUT_BYTES) {
       return { status: 413, body: { error: "tool_input_too_large" } };
@@ -6650,7 +8037,7 @@ var GovernanceService = class {
     const entryBytes = inputBytes + byteLength(req.metadata ?? {}) + byteLength({
       tool: req.tool.name,
       agent_id: req.agent_id,
-      session_id: req.session_id,
+      session_id: sessionId,
       origin: req.origin
     });
     if (!this.caches.has(req.origin) && this.caches.size >= MAX_ORIGINS) {
@@ -6672,7 +8059,8 @@ var GovernanceService = class {
     const pipeline = decide({
       toolName,
       toolArguments: req.arguments,
-      sessionId: req.session_id ?? void 0,
+      sessionId: sessionId ?? void 0,
+      sessionStrategySummary: this.session.strategySummary,
       policy: this.policy,
       environment: this.environment,
       evidenceStore: this.evidenceStore,
@@ -6689,6 +8077,8 @@ var GovernanceService = class {
     const plans = [];
     let limitsBlock;
     let ruleLimitOk = true;
+    let sessionUnresolvedDeny = false;
+    let dryRunSessionUnresolved = false;
     const reservedThisCall = [];
     const reserve = (key) => {
       const preexisting = this.senderKeys.has(key);
@@ -6703,12 +8093,14 @@ var GovernanceService = class {
     if (pipeline.isDryRun) {
       wire = "dry_run";
       if (decision.action === "rate_limit") {
-        const planned = this.planRate(decision, toolName, req.session_id, senderId);
+        const planned = this.planRate(decision, toolName, sessionId, senderId);
         if (planned?.block) limitsBlock = { rate: planned.block };
+        if (planned?.sessionUnresolved) dryRunSessionUnresolved = true;
         ruleLimitOk = planned?.allowed ?? true;
       } else if (decision.action === "spend_limit") {
-        const planned = this.planSpend(decision, toolName, req.session_id, req.arguments, senderId);
+        const planned = this.planSpend(decision, toolName, sessionId, req.arguments, senderId);
         if (planned?.block) limitsBlock = { spend: planned.block };
+        if (planned?.sessionUnresolved) dryRunSessionUnresolved = true;
         ruleLimitOk = planned?.allowed ?? true;
       }
     } else if (decision.action === "deny") {
@@ -6716,21 +8108,31 @@ var GovernanceService = class {
     } else if (decision.action === "require_approval") {
       wire = "require_approval";
     } else if (decision.action === "rate_limit") {
-      const planned = this.planRate(decision, toolName, req.session_id, senderId);
-      if (planned?.plan && !reserve(planned.plan.key)) {
-        return { status: 503, body: { error: "limit_capacity_exhausted" } };
+      const planned = this.planRate(decision, toolName, sessionId, senderId);
+      if (planned?.sessionUnresolved) {
+        wire = "deny";
+        sessionUnresolvedDeny = true;
+      } else {
+        if (planned?.plan && !reserve(planned.plan.key)) {
+          return { status: 503, body: { error: "limit_capacity_exhausted" } };
+        }
+        if (planned?.plan) plans.push(planned.plan);
+        limitsBlock = planned?.block ? { rate: planned.block } : void 0;
+        wire = planned?.allowed ? "allow" : "rate_limited";
       }
-      if (planned?.plan) plans.push(planned.plan);
-      limitsBlock = planned?.block ? { rate: planned.block } : void 0;
-      wire = planned?.allowed ? "allow" : "rate_limited";
     } else if (decision.action === "spend_limit") {
-      const planned = this.planSpend(decision, toolName, req.session_id, req.arguments, senderId);
-      if (planned?.plan && !reserve(planned.plan.key)) {
-        return { status: 503, body: { error: "limit_capacity_exhausted" } };
+      const planned = this.planSpend(decision, toolName, sessionId, req.arguments, senderId);
+      if (planned?.sessionUnresolved) {
+        wire = "deny";
+        sessionUnresolvedDeny = true;
+      } else {
+        if (planned?.plan && !reserve(planned.plan.key)) {
+          return { status: 503, body: { error: "limit_capacity_exhausted" } };
+        }
+        if (planned?.plan) plans.push(planned.plan);
+        limitsBlock = planned?.block ? { spend: planned.block } : void 0;
+        wire = planned?.allowed ? "allow" : "spend_limited";
       }
-      if (planned?.plan) plans.push(planned.plan);
-      limitsBlock = planned?.block ? { spend: planned.block } : void 0;
-      wire = planned?.allowed ? "allow" : "spend_limited";
     } else {
       wire = "allow";
     }
@@ -6742,14 +8144,27 @@ var GovernanceService = class {
     let budgetTicketTimeoutMs;
     let budgetTriggeredApproval = false;
     if (this.budgetEngine && (wire === "allow" || wire === "require_approval" || wire === "dry_run")) {
+      const budgetSessionGate = gateSession(sessionId, this.session.onUnresolved);
       const { charges, failures } = this.budgetEngine.resolveCharges({
         toolName,
         toolArguments: req.arguments,
-        sessionId: req.session_id,
+        sessionId: budgetSessionGate.ok ? budgetSessionGate.session : null,
         senderId
       });
-      if (charges.length > 0 || failures.length > 0) {
-        const peek = charges.length > 0 ? this.budgetEngine.peekAll(charges) : { allowed: true, entries: [] };
+      const gatedCharges = charges.length > 0 || failures.length > 0 ? gateBudgetCharges({ charges, failures }, budgetSessionGate) : void 0;
+      if (gatedCharges && !gatedCharges.ok) {
+        warnSessionUnresolvedEngagementOnce(this.session.strategySummary);
+        if (wire === "dry_run") {
+          budgetDryRunOk = false;
+          dryRunSessionUnresolved = true;
+        } else {
+          releaseReservations();
+          plans.length = 0;
+          wire = "deny";
+          sessionUnresolvedDeny = true;
+        }
+      } else if (gatedCharges) {
+        const peek = charges.length > 0 ? this.budgetEngine.peekAll(gatedCharges.charges) : { allowed: true, entries: [] };
         budgetsBlock = [
           ...peek.entries.map((entry2) => budgetWireBlock(entry2)),
           ...failures.map((failure) => budgetFailureBlock(failure))
@@ -6771,19 +8186,16 @@ var GovernanceService = class {
         } else {
           if (breaches.length > 0) budgetDryRunOk = false;
           if (wire !== "dry_run") {
-            for (const [index, charge] of charges.entries()) {
-              if (!reserve(charge.bucketKey)) {
+            const frozen = freezeGatedPlans(
+              gatedCharges.charges,
+              charges.map((_, index) => peek.entries[index]?.allowed === false)
+            );
+            for (const plan of frozen) {
+              if (!reserve(plan.bucketKey)) {
                 releaseReservations();
                 return { status: 503, body: { error: "limit_capacity_exhausted" } };
               }
-              plans.push({
-                kind: "budget",
-                budget: charge.budget,
-                bucketKey: charge.bucketKey,
-                amount: charge.amount,
-                generation: charge.generation,
-                breached: peek.entries[index]?.allowed === false
-              });
+              plans.push(plan);
             }
             if (breaches.length > 0) {
               budgetBreachEntries = breaches;
@@ -6832,12 +8244,21 @@ var GovernanceService = class {
         suggestion: budgetDenial.invalid.length > 0 ? "Retry with a non-negative finite amount in the expected field." : "Wait for the window to reset or reduce the amount."
       };
     }
+    if (sessionUnresolvedDeny) {
+      const message = sessionUnresolvedControlMessage(this.session.strategySummary);
+      responseBody["reason"] = message;
+      responseBody["feedback"] = {
+        message,
+        suggestion: "Send a session_id the identity policy accepts, or set session.on_unresolved: anonymous to restore shared pooling."
+      };
+    }
     if (limitsBlock) responseBody["limits"] = limitsBlock;
     if (wire === "dry_run") {
       responseBody["dry_run"] = {
         would_forward: (decision.action === "allow" || (decision.action === "rate_limit" || decision.action === "spend_limit") && ruleLimitOk) && !pipeline.evidenceBlocked && budgetDryRunOk,
         evidence_satisfied: !pipeline.evidenceBlocked,
-        limits_ok: ruleLimitOk && budgetDryRunOk
+        limits_ok: ruleLimitOk && budgetDryRunOk,
+        ...dryRunSessionUnresolved ? { session_unresolved: true } : {}
       };
     }
     if (pipeline.driftEvent) {
@@ -6848,7 +8269,7 @@ var GovernanceService = class {
         timestampIso,
         origin: req.origin,
         agentId: req.agent_id,
-        sessionId: req.session_id,
+        sessionId,
         toolName,
         toolInput: req.arguments ?? {},
         metadata: req.metadata,
@@ -6863,7 +8284,9 @@ var GovernanceService = class {
         // limitsBlock is also the response's `limits`, and the audit writer
         // buffers records by reference until flush — a direct embedder
         // editing the returned body must not be able to rewrite evidence.
-        limitsChain: limitsBlock ? structuredClone(limitsBlock) : void 0
+        limitsChain: limitsBlock ? structuredClone(limitsBlock) : void 0,
+        sessionUnresolved: sessionUnresolvedDeny,
+        sessionChain: pipeline.sessionBlocked
       });
       this.tombstones.set(evaluationId, {
         auditRecordId: auditId,
@@ -6896,7 +8319,7 @@ var GovernanceService = class {
         // rewrite it (same guard as the pending entry's evidence below).
         tool_input: structuredClone(req.arguments ?? {}),
         matched_rule: decision.matchedRule,
-        session_id: req.session_id,
+        session_id: sessionId,
         origin: req.origin,
         timeout_ms: timeoutMs,
         breached_budgets: budgetBreachContexts
@@ -6914,7 +8337,7 @@ var GovernanceService = class {
       evaluationId,
       origin: req.origin,
       agentId: req.agent_id,
-      sessionId: req.session_id,
+      sessionId,
       toolName,
       // Cloned: direct embedders share these references and could otherwise
       // mutate the audit evidence (and desync the byte accounting) after
@@ -7133,7 +8556,9 @@ var GovernanceService = class {
       timestampIso: new Date(this.now()).toISOString(),
       origin: req.origin,
       agentId: req.agent_id,
-      sessionId: req.session_id,
+      // Same trim-empty normalization as /evaluate: a whitespace-only id
+      // must not land in the audit row as attributed sideband identity.
+      sessionId: isWellFormedSessionId(req.session_id) ? req.session_id : null,
       toolName,
       toolInput: { ...req.package },
       metadata: req.metadata,
@@ -7450,7 +8875,18 @@ var GovernanceService = class {
     if (!this.rateLimiter || !limits?.maxCalls || !limits.windowMs) {
       return { allowed: true };
     }
-    const key = buildLimitKey(limits.key, toolName, sessionId, senderId);
+    let key;
+    if (limits.key === "session") {
+      const gate = gateSession(sessionId, this.session.onUnresolved);
+      if (!gate.ok) {
+        warnSessionUnresolvedEngagementOnce(this.session.strategySummary);
+        return { allowed: false, sessionUnresolved: true };
+      }
+      if (gate.anonymous) warnAnonymousPoolingOnce();
+      key = sessionLimitKey(gate.session);
+    } else {
+      key = buildLimitKey(limits.key, toolName, senderId);
+    }
     const peek = this.rateLimiter.peek({
       key,
       maxCalls: limits.maxCalls,
@@ -7470,10 +8906,19 @@ var GovernanceService = class {
   planSpend(decision, toolName, sessionId, args, senderId) {
     const maxSpend = decision.matchedRule?.limits?.maxSpend;
     if (!this.spendLimiter || !maxSpend) return { allowed: true };
-    const key = spendBucketKey(
-      buildLimitKey(maxSpend.key, toolName, sessionId, senderId),
-      decision.matchedRule.index
-    );
+    let baseKey;
+    if (maxSpend.key === "session") {
+      const gate = gateSession(sessionId, this.session.onUnresolved);
+      if (!gate.ok) {
+        warnSessionUnresolvedEngagementOnce(this.session.strategySummary);
+        return { allowed: false, sessionUnresolved: true };
+      }
+      if (gate.anonymous) warnAnonymousPoolingOnce();
+      baseKey = sessionLimitKey(gate.session);
+    } else {
+      baseKey = buildLimitKey(maxSpend.key, toolName, senderId);
+    }
+    const key = spendBucketKey(baseKey, decision.matchedRule.index);
     const rawAmount = resolvePath(maxSpend.field, args ?? {});
     if (typeof rawAmount !== "number" || !Number.isFinite(rawAmount) || rawAmount < 0) {
       return { allowed: false, block: { reason: "invalid_amount", limit: maxSpend.limit } };
@@ -7505,18 +8950,15 @@ var GovernanceService = class {
   /** Commit every plan of one call at /audit time; returns the chain blocks. */
   commitPlans(entry, actualAmount, auditId, approvalStatus) {
     let chain;
-    const budgetPlans = entry.plans.filter((plan) => plan.kind === "budget");
+    const budgetPlans = entry.plans.filter(
+      (plan) => plan.kind === "budget"
+    );
     if (budgetPlans.length > 0 && this.budgetEngine) {
       const kinds = new Map(
         budgetPlans.filter((plan) => plan.breached && approvalStatus === "approved").map((plan) => [plan.budget.name, "approved_overage"])
       );
       const snapshots = this.budgetEngine.recordAll(
-        budgetPlans.map((plan) => ({
-          budget: plan.budget,
-          bucketKey: plan.bucketKey,
-          amount: actualAmount ?? plan.amount,
-          generation: plan.generation
-        })),
+        remintDeferredCharges(budgetPlans, actualAmount),
         {
           kind: "spend",
           ...kinds.size > 0 ? { kinds } : {},
@@ -7587,6 +9029,12 @@ var GovernanceService = class {
     if (!this.auditWriter) return id;
     const blockReason = deriveBlockReason(args);
     let evidenceChain = args.limitsChain ?? null;
+    if (args.sessionUnresolved || args.sessionChain) {
+      evidenceChain = {
+        ...evidenceChain ?? {},
+        session: { unresolved: true, tried: this.session.strategySummary }
+      };
+    }
     if (args.sidebandUnreported) {
       evidenceChain = {
         ...evidenceChain ?? {},
@@ -7602,6 +9050,9 @@ var GovernanceService = class {
     const record = {
       timestamp: args.timestampIso,
       session_id: args.sessionId,
+      // Adapter-supplied ids are attributed to the sideband door itself —
+      // the MCP resolver's source vocabulary does not apply here.
+      session_source: args.sessionId != null ? "sideband" : null,
       agent_id: args.agentId,
       environment: this.environment ?? null,
       tool_name: args.toolName,
@@ -7624,7 +9075,9 @@ var GovernanceService = class {
       dry_run: args.dryRun,
       record_kind: args.recordKind,
       origin: args.origin,
-      metadata: args.metadata
+      metadata: args.metadata,
+      // The sideband has no MCP wire, so no protocol claim exists.
+      protocol_version: null
     };
     const isEnforcement = args.recordKind === "evaluation_expired" || blockReason !== null || args.approvalStatus != null;
     if (isEnforcement) this.auditWriter.pushImmediate(record, id);
@@ -7643,6 +9096,7 @@ function deriveBlockReason(args) {
   if (args.recordKind === "install_scan") return args.wire === "deny" ? "install_denied" : null;
   if (args.dryRun) return null;
   if (args.budgetBreachBlocked) return "budget_exceeded";
+  if (args.sessionUnresolved) return "session_unresolved";
   if (args.approvalStatus === "denied") return "approval_denied";
   if (args.approvalStatus === "timeout") return "approval_timeout";
   if (args.approvalStatus === "cancelled") return "cancelled";
@@ -7681,10 +9135,8 @@ function policyCanRequireApproval(policy) {
   }
   return policy.rules.some((rule) => rule.action === "require_approval");
 }
-function buildLimitKey(keyType, toolName, sessionId, senderId) {
+function buildLimitKey(keyType, toolName, senderId) {
   switch (keyType) {
-    case "session":
-      return `session:${sessionId ?? "unknown"}`;
     case "sender_id":
       return `sender:${senderId ?? "unknown"}`;
     case "agent":
@@ -8894,7 +10346,11 @@ var BudgetEngine = class {
     }
     return { charges, failures };
   }
-  /** Check every charge without mutating. All-or-nothing: one deny flips `allowed`. */
+  /**
+   * Check every charge without mutating. All-or-nothing: one deny flips
+   * `allowed`. Accepts only gate-branded charges (issue #218) — a caller
+   * cannot peek budget state without having run the session engagement check.
+   */
   peekAll(charges) {
     const entries = charges.map((charge) => this.snapshot(charge));
     return { allowed: entries.every((entry) => entry.allowed), entries };
@@ -9664,7 +11120,11 @@ var CSV_HEADERS = [
   "matched_rule_index",
   "record_kind",
   "origin",
-  "metadata"
+  "metadata",
+  // Appended LAST (issues #218, #219): positional consumers of the existing
+  // columns keep working — new columns always go at the end.
+  "session_source",
+  "protocol_version"
 ];
 var FORMULA_PREFIXES = /^[=+\-@\t\r]/;
 function csvEscape(value) {
@@ -10541,6 +12001,13 @@ upstream:
 
 # environment: production
 
+# session:
+#   identity: # ordered; first match wins
+#     - source: header
+#       name: x-helio-session-id
+#     - source: legacy_header # verbatim Mcp-Session-Id (deprecation window)
+#   on_unresolved: deny # deny | anonymous
+
 # policies:
 #   default: allow
 #   dry_run: false
@@ -10600,90 +12067,6 @@ function printConfigErrorDetails(error, prefix = "") {
     console.error(`${prefix}  ${detail.path}: ${detail.message}`);
   }
 }
-var ANNOTATION_PRIME_INITIAL_WAIT_MS = 1500;
-var ANNOTATION_PRIME_RETRY_BASE_MS = 1e3;
-var ANNOTATION_PRIME_RETRY_MAX_MS = 3e4;
-var ANNOTATION_PRIME_RETRY_JITTER_MS = 250;
-function computePrimeRetryDelayMs(attempt) {
-  const exponent = Math.max(0, attempt - 1);
-  const baseDelay = Math.min(
-    ANNOTATION_PRIME_RETRY_MAX_MS,
-    ANNOTATION_PRIME_RETRY_BASE_MS * 2 ** exponent
-  );
-  const jitter = Math.floor(Math.random() * ANNOTATION_PRIME_RETRY_JITTER_MS);
-  return Math.min(ANNOTATION_PRIME_RETRY_MAX_MS, baseDelay + jitter);
-}
-async function startAnnotationPrimeLoop(governedForwarder) {
-  let stopped = false;
-  let primed = false;
-  let retryAttempt = 0;
-  let retryTimer;
-  const clearRetryTimer = () => {
-    if (!retryTimer) return;
-    clearTimeout(retryTimer);
-    retryTimer = void 0;
-  };
-  const stop = () => {
-    stopped = true;
-    clearRetryTimer();
-  };
-  const scheduleRetry = () => {
-    if (stopped || primed || retryTimer) return;
-    retryAttempt += 1;
-    const delayMs = computePrimeRetryDelayMs(retryAttempt);
-    console.error(
-      `[helio] Annotation cache prime retry ${String(retryAttempt)} scheduled in ${String(delayMs)}ms`
-    );
-    retryTimer = setTimeout(() => {
-      retryTimer = void 0;
-      void runPrimeAttempt("retry");
-    }, delayMs);
-    retryTimer.unref();
-  };
-  const handlePrimeResult = (phase, result) => {
-    if (stopped || primed) return;
-    if (result.success) {
-      primed = true;
-      clearRetryTimer();
-      const prefix = phase === "initial" ? "[helio] Annotation cache primed" : `[helio] Annotation cache primed after retry ${String(retryAttempt)}`;
-      console.error(
-        `${prefix}: ${String(result.toolsCached)} tool definitions baselined for drift detection (baselines are per-process; a restart re-baselines \u2014 review tool_drift audit records before restarting)`
-      );
-      return;
-    }
-    const reason = result.reason ?? "unknown reason";
-    if (phase === "initial") {
-      console.error(
-        `[helio] Annotation cache priming failed: ${reason} \u2014 undocumented tools will be denied (fail-closed) until priming succeeds`
-      );
-    } else {
-      console.error(
-        `[helio] Annotation cache prime retry ${String(retryAttempt)} failed: ${reason} \u2014 still fail-closed`
-      );
-    }
-    scheduleRetry();
-  };
-  const runPrimeAttempt = async (phase) => {
-    const result = await governedForwarder.primeAnnotationCache();
-    handlePrimeResult(phase, result);
-  };
-  const initialAttempt = runPrimeAttempt("initial");
-  const initialOutcome = await Promise.race([
-    initialAttempt.then(() => "completed"),
-    new Promise((resolve2) => {
-      setTimeout(() => {
-        resolve2("timeout");
-      }, ANNOTATION_PRIME_INITIAL_WAIT_MS).unref();
-    })
-  ]);
-  if (initialOutcome === "timeout") {
-    console.error(
-      `[helio] Annotation cache priming did not complete within ${String(ANNOTATION_PRIME_INITIAL_WAIT_MS)}ms; continuing startup fail-closed and retrying in background`
-    );
-    scheduleRetry();
-  }
-  return { stop };
-}
 async function startCommand(configPath, options) {
   let config;
   try {
@@ -10731,6 +12114,8 @@ async function startCommand(configPath, options) {
         block_reason: record.block_reason,
         approval_status: record.approval_status,
         session_id: record.session_id,
+        session_source: record.session_source,
+        protocol_version: record.protocol_version,
         agent_id: record.agent_id,
         environment: record.environment,
         timestamp: record.timestamp,
@@ -10815,6 +12200,7 @@ async function startCommand(configPath, options) {
     }
   });
   budgetEngine.hydrate();
+  const session = compileSessionIdentity(config.session);
   const governedForwarder = new GovernedForwarder(forwarder, policy, {
     environment: config.environment,
     auditWriter,
@@ -10822,13 +12208,17 @@ async function startCommand(configPath, options) {
     approvalRouter,
     rateLimiter,
     spendLimiter,
-    budgetEngine
+    budgetEngine,
+    session
   });
-  const annotationPrime = await startAnnotationPrimeLoop(governedForwarder);
+  const annotationPrime = await startAnnotationPrimeLoop(governedForwarder, policy.toolRevalidation);
   const hasSlackChannels = [...channels.values()].some((ch) => ch.type === "slack");
   const slackActionApp = hasSlackChannels ? createSlackActionApp({ router: approvalRouter, channels }) : void 0;
   const app = createApp(config, governedForwarder, {
-    slackActionApp
+    slackActionApp,
+    onHeaderMismatch: (rejection) => {
+      auditWriter.pushImmediate(buildHeaderMismatchAuditRecord(rejection, config.environment));
+    }
   });
   const handle = startServer(app, config);
   let sidebandHandle;
@@ -10862,6 +12252,7 @@ async function startCommand(configPath, options) {
       rateLimiter,
       spendLimiter,
       budgetEngine,
+      session,
       auditWriter,
       approvalTimeoutMs: parseDuration(config.approval.timeout),
       ttlMs: parseDuration(config.sdk.evaluation_ttl)
@@ -10983,6 +12374,7 @@ async function startCommand(configPath, options) {
         }
         budgetEngine.reconcile(newBudgets);
         governedForwarder.updatePolicy(newPolicy);
+        annotationPrime.reconfigure(newPolicy.toolRevalidation);
         governanceService?.updatePolicy(newPolicy);
         const budgetTotal = newBudgets.length;
         console.error(