feat(mcpx): re-initialize on a legacy session 404 and retry once (#1637)

pkgs/mcpx/docs/spec/conformance-matrix.md

@@ -2,7 +2,7 @@
 
 Generated by `internal/conformance` (`MCPX_UPDATE_MATRIX=1 go test ./internal/conformance -run TestMatrix`); do not edit.
 
-Generated from inputs `e521a082e8f389bb` (sha256 of docs/spec/requirements.md, internal/conformance/overrides/*.json, internal/conformance/coverage*.go). `TestMatrix` regenerates this file and fails when it differs, so it describes the tree it is committed in.
+Generated from inputs `ad5f12fd46e96bac` (sha256 of docs/spec/requirements.md, internal/conformance/overrides/*.json, internal/conformance/coverage*.go). `TestMatrix` regenerates this file and fails when it differs, so it describes the tree it is committed in.
 
 Every normative requirement of every revision (catalogue: `docs/spec/requirements.md`), for mcpx as a server and as a client. A requirement is *tested* when a named test verifies it in that revision, *n/a* when it does not bind mcpx in that role, and a *gap* when it binds mcpx and mcpx does not meet it yet, with the issue that tracks it. Run exactly the covering tests with `go run ./internal/conformance/cmd/covering`.
 
@@ -28,7 +28,7 @@ Every normative requirement of every revision (catalogue: `docs/spec/requirement
 | 2025-03-26 | server | SHOULD NOT | 4 | 3 | 1 | 0 | 1 |
 | 2025-03-26 | server | MAY | 19 | 16 | 3 | 0 | 18 |
 | 2025-03-26 | server | other | 11 | 11 | 0 | 0 | 1 |
-| 2025-03-26 | client | MUST | 41 | 29 | 12 | 0 | 40 |
+| 2025-03-26 | client | MUST | 41 | 30 | 11 | 0 | 40 |
 | 2025-03-26 | client | MUST NOT | 12 | 11 | 1 | 0 | 3 |
 | 2025-03-26 | client | SHOULD | 44 | 32 | 12 | 0 | 59 |
 | 2025-03-26 | client | SHOULD NOT | 2 | 1 | 1 | 0 | 3 |
@@ -40,7 +40,7 @@ Every normative requirement of every revision (catalogue: `docs/spec/requirement
 | 2025-06-18 | server | SHOULD NOT | 4 | 3 | 1 | 0 | 1 |
 | 2025-06-18 | server | MAY | 17 | 15 | 2 | 0 | 18 |
 | 2025-06-18 | server | other | 15 | 15 | 0 | 0 | 3 |
-| 2025-06-18 | client | MUST | 52 | 35 | 17 | 0 | 49 |
+| 2025-06-18 | client | MUST | 52 | 36 | 16 | 0 | 49 |
 | 2025-06-18 | client | MUST NOT | 13 | 11 | 2 | 0 | 5 |
 | 2025-06-18 | client | SHOULD | 52 | 38 | 14 | 0 | 63 |
 | 2025-06-18 | client | SHOULD NOT | 2 | 1 | 1 | 0 | 3 |
@@ -52,7 +52,7 @@ Every normative requirement of every revision (catalogue: `docs/spec/requirement
 | 2025-11-25 | server | SHOULD NOT | 11 | 9 | 2 | 0 | 3 |
 | 2025-11-25 | server | MAY | 27 | 25 | 2 | 0 | 28 |
 | 2025-11-25 | server | other | 19 | 19 | 0 | 0 | 2 |
-| 2025-11-25 | client | MUST | 76 | 54 | 22 | 0 | 104 |
+| 2025-11-25 | client | MUST | 76 | 55 | 21 | 0 | 104 |
 | 2025-11-25 | client | MUST NOT | 16 | 14 | 2 | 0 | 19 |
 | 2025-11-25 | client | SHOULD | 67 | 45 | 22 | 0 | 92 |
 | 2025-11-25 | client | SHOULD NOT | 5 | 4 | 1 | 0 | 9 |
@@ -760,7 +760,7 @@ Every normative requirement of every revision (catalogue: `docs/spec/requirement
 | [streamable-http-client-echoes-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | client | n/a: addresses the other side | tested: `conformance.TestTransportClient/2025-03-26/transport-streamable-http/streamable-http-client-echoes-session` |
 | [streamable-http-server-400-missing-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | SHOULD | server | n/a: mcpx does not require one (stateless fallback | n/a: addresses the other side |
 | [streamable-http-server-404-terminated-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | server | tested: `conformance.TestTransportServer/2025-03-26/transport-streamable-http/streamable-http-server-404-terminated-session` | n/a: addresses the other side |
-| [streamable-http-client-reinit-on-404](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | client | n/a: addresses the other side | **gap** #203: a 404 for the session is returned as an error; no new initialize |
+| [streamable-http-client-reinit-on-404](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | client | n/a: addresses the other side | tested: `mcpclient.TestLegacySession404Recovery/2025-11-25/transport/client-reinitializes-on-session-404-and-retries-once@2025-03-26,2025-06-18,2025-11-25` |
 | [streamable-http-client-delete-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | SHOULD | client | n/a: addresses the other side | tested: `conformance.TestTransportClient/2025-03-26/transport-streamable-http/streamable-http-client-delete-session` |
 | [streamable-http-server-may-405-delete](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MAY | server | tested: `conformance.TestTransportServer/2025-03-26/transport-streamable-http/streamable-http-server-may-405-delete` | n/a: addresses the other side |
 
@@ -1190,7 +1190,7 @@ Every normative requirement of every revision (catalogue: `docs/spec/requirement
 | [streamable-http-client-echoes-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | client | n/a: addresses the other side | tested: `conformance.TestTransportClient/2025-06-18/transport-streamable-http/streamable-http-client-echoes-session` |
 | [streamable-http-server-400-missing-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | SHOULD | server | n/a: mcpx does not require one (stateless fallback | n/a: addresses the other side |
 | [streamable-http-server-404-terminated-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | server | tested: `conformance.TestTransportServer/2025-06-18/transport-streamable-http/streamable-http-server-404-terminated-session` | n/a: addresses the other side |
-| [streamable-http-client-reinit-on-404](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | client | n/a: addresses the other side | **gap** #203: a 404 for the session is returned as an error; no new initialize |
+| [streamable-http-client-reinit-on-404](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | client | n/a: addresses the other side | tested: `mcpclient.TestLegacySession404Recovery/2025-11-25/transport/client-reinitializes-on-session-404-and-retries-once@2025-03-26,2025-06-18,2025-11-25` |
 | [streamable-http-client-delete-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | SHOULD | client | n/a: addresses the other side | tested: `conformance.TestTransportClient/2025-06-18/transport-streamable-http/streamable-http-client-delete-session` |
 | [streamable-http-server-may-405-delete](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MAY | server | tested: `conformance.TestTransportServer/2025-06-18/transport-streamable-http/streamable-http-server-may-405-delete` | n/a: addresses the other side |
 | [streamable-http-protocol-version-header-is-negotiated](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#protocol-version-header) | SHOULD | client | n/a: addresses the other side | tested: `conformance.TestTransportClient/2025-06-18/transport-streamable-http/streamable-http-protocol-version-header-is-negotiated` |
@@ -1806,7 +1806,7 @@ Every normative requirement of every revision (catalogue: `docs/spec/requirement
 | [streamable-http-client-echoes-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | client | n/a: addresses the other side | tested: `conformance.TestTransportClient/2025-11-25/transport-streamable-http/streamable-http-client-echoes-session` |
 | [streamable-http-server-400-missing-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | SHOULD | server | n/a: mcpx does not require one (stateless fallback | n/a: addresses the other side |
 | [streamable-http-server-404-terminated-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | server | tested: `conformance.TestTransportServer/2025-11-25/transport-streamable-http/streamable-http-server-404-terminated-session` | n/a: addresses the other side |
-| [streamable-http-client-reinit-on-404](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | client | n/a: addresses the other side | **gap** #203: a 404 for the session is returned as an error; no new initialize |
+| [streamable-http-client-reinit-on-404](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MUST | client | n/a: addresses the other side | tested: `mcpclient.TestLegacySession404Recovery/2025-11-25/transport/client-reinitializes-on-session-404-and-retries-once@2025-03-26,2025-06-18,2025-11-25` |
 | [streamable-http-client-delete-session](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | SHOULD | client | n/a: addresses the other side | tested: `conformance.TestTransportClient/2025-11-25/transport-streamable-http/streamable-http-client-delete-session` |
 | [streamable-http-server-may-405-delete](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) | MAY | server | tested: `conformance.TestTransportServer/2025-11-25/transport-streamable-http/streamable-http-server-may-405-delete` | n/a: addresses the other side |
 | [streamable-http-protocol-version-header-is-negotiated](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#protocol-version-header) | SHOULD | client | n/a: addresses the other side | tested: `conformance.TestTransportClient/2025-11-25/transport-streamable-http/streamable-http-protocol-version-header-is-negotiated` |

pkgs/mcpx/docs/spec/requirements.md

@@ -272,7 +272,7 @@ Most 2025-11-25 growth is the tasks page (57 rows) and the elicitation rewrite;
 | streamable-http-client-echoes-session | 2025-03-26..2025-11-25 | client | MUST | transport-streamable-http | "clients using the Streamable HTTP transport **MUST** include it in the `Mcp-Session-Id` header on all of their subsequent HTTP requests." | https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management | n/a | yes — also sends it to modern servers (2026 server SHOULD ignore) | |
 | streamable-http-server-400-missing-session | 2025-03-26..2025-11-25 | server | SHOULD | transport-streamable-http | "Servers that require a session ID **SHOULD** respond to requests without an `Mcp-Session-Id` header (other than initialization) with HTTP 400 Bad Request." | https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management | n/a — mcpx does not require one (stateless fallback) | n/a | |
 | streamable-http-server-404-terminated-session | 2025-03-26..2025-11-25 | server | MUST | transport-streamable-http | "The server **MAY** terminate the session at any time, after which it **MUST** respond to requests containing that session ID with HTTP 404 Not Found." | https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management | yes — an ended or unknown session id is 404; tested, see `conformance-matrix.md` | n/a |  |
-| streamable-http-client-reinit-on-404 | 2025-03-26..2025-11-25 | client | MUST | transport-streamable-http | "it **MUST** start a new session by sending a new `InitializeRequest` without a session ID attached." | https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management | n/a | **gap** — 404 surfaces as `http 404` error; session id kept | Under 2026 a 404 means "method not found" (C7). |
+| streamable-http-client-reinit-on-404 | 2025-03-26..2025-11-25 | client | MUST | transport-streamable-http | "it **MUST** start a new session by sending a new `InitializeRequest` without a session ID attached." | https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management | n/a | yes — a session 404 triggers one re-initialize (no session id on it) and one retry on the new session; tested, see `conformance-matrix.md` | Under 2026 a 404 means "method not found" (C7). |
 | streamable-http-client-delete-session | 2025-03-26..2025-11-25 | client | SHOULD | transport-streamable-http | "Clients that no longer need a particular session ... **SHOULD** send an HTTP DELETE to the MCP endpoint with the `Mcp-Session-Id` header" | https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management | accepts — 204 | yes — on `Close` | |
 | streamable-http-server-may-405-delete | 2025-03-26..2025-11-25 | server | MAY | transport-streamable-http | "The server **MAY** respond to this request with HTTP 405 Method Not Allowed" | https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management | chooses 204 | tolerates any status | |
 | streamable-http-protocol-version-header-is-negotiated | 2025-06-18..2025-11-25 | client | SHOULD | transport-streamable-http | "The protocol version sent by the client **SHOULD** be the one negotiated during initialization." | https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#protocol-version-header | n/a | yes — the header carries the negotiated revision; tested, see `conformance-matrix.md` |  |

pkgs/mcpx/internal/conformance/coverage_transport.go

@@ -16,6 +16,7 @@ func init() {
 		C("streamable-http-x-mcp-header-client-must-mirror", "mcpclient.TestParamHeaders/2026-07-28/transport/param-headers-mirror-and-omit-null"),
 		C("streamable-http-client-rejects-invalid-x-mcp-header", "mcpclient.TestToolHeaderAnnotations/2026-07-28/transport/client-rejects-invalid-x-mcp-header", "mcpclient.TestModernHTTPHeaders/2026-07-28/transport/client-excludes-tool-with-invalid-x-mcp-header"),
 		C("streamable-http-client-relist-on-header-mismatch", "mcpclient.TestModernHTTPHeaders/2026-07-28/transport/client-relists-and-retries-on-header-mismatch"),
+		C("streamable-http-client-reinit-on-404", "mcpclient.TestLegacySession404Recovery/2025-11-25/transport/client-reinitializes-on-session-404-and-retries-once@2025-03-26,2025-06-18,2025-11-25"),
 		C("streamable-http-client-reissue-broken-request", "mcpclient.TestModernReissueBrokenRequest/2026-07-28/transport/client-reissues-broken-request-once"),
 		C("streamable-http-client-polls-after-close", "mcpclient.TestLegacyHTTPStreamResumption/2025-11-25/transport/client-resumes-closed-stream-with-last-event-id-after-retry"),
 		C("streamable-http-client-respects-retry", "mcpclient.TestLegacyHTTPStreamResumption/2025-11-25/transport/client-resumes-closed-stream-with-last-event-id-after-retry"),
@@ -112,7 +113,6 @@ func init() {
 		),
 	)
 	registerGaps(
-		Gap{ID: "streamable-http-client-reinit-on-404", Side: Client, Issue: "#203", Why: "a 404 for the session is returned as an error; no new initialize"},
 		Gap{ID: "stdio-client-restart-crashed-server", Side: Client, Issue: "#257", Why: "unverified: the in-flight call fails and the pool respawns only on the next acquire, subject to its start-failure cooldown"},
 	)
 }

pkgs/mcpx/internal/conformance/requirements.json

@@ -4927,11 +4927,8 @@
       "server": "n/a:addresses the other side"
     },
     "notes": {
-      "client": "**gap** — 404 surfaces as `http 404` error; session id kept",
+      "client": "yes — a session 404 triggers one re-initialize (no session id on it) and one retry on the new session; tested, see `conformance-matrix.md`",
       "server": "n/a"
-    },
-    "claims": {
-      "client": "gap"
     }
   },
   {