mcpx: Phase 1 of #1634 — re-initialize on a legacy session 404 and retry the request once

Phase 1 of design #1634 (mcpx client session & stream recovery). Design doc: files/designs/code-mcpx-client-session-stream-recovery.md in the keep-the-four-repos-healthy goal workspace.

Scope

Recover transparently when a legacy HTTP upstream forgets the session (restarts) mid-life: forget the dead session, re-initialize once, retry the request once.

Trigger, narrowly: a request (never a notification, never initialize itself) fails with HTTPStatusError 404, the client era is legacy, and the failed request actually carried a session id. Any other 404 behaves exactly as today.
internal/mcpclient/http.go: add a small transport seam the client can interface-assert (the interface{ setNegotiated(string) } pattern in client.go): atomically report-and-clear the held session id (working name forgetSession() bool). The fresh initialize must go out with no session id, and no later request may echo the dead one. Stdio transports do not implement the seam; recovery is HTTP-only.
internal/mcpclient/client.go: recovery in the request path (roundTrip/call layer) reusing the existing initializeLegacy/finishLegacy unchanged. Re-initialize is singleflight across concurrent calls — a client-level mutex plus a session generation, so N concurrent 404s from one upstream restart produce exactly one initialize; calls whose generation was already replaced just retry on the new session.
Retry the original request exactly once through roundTrip (fresh pending entry, new request id). A second 404, or a failed re-initialize, surfaces the error as today. No retry loop.
After a successful re-initialize, fire the existing catalogue-invalidation signal (invalidate path → Notifications.OnListChanged) for tools, resources and prompts — a restarted upstream's catalogue is not the cached one. finishLegacy already refreshes ServerInfo/Capabilities and restarts the GET listen stream for ≥2025-03-26.
Modern era is excluded: 2026 has no sessions (TR-30); a modern 404 stays an ordinary error.
Retire conformance gap streamable-http-client-reinit-on-404 (internal/conformance/coverage_transport.go).

Evidence (main `ed8e591`, 2026-10-28)

Gap at internal/conformance/coverage_transport.go:115 (origin mcpx client: legacy Streamable HTTP and stdio robustness — session 404, GET stream, SSE retry, string ids, stream timeout, version header dezren39/darwin-nix#203): "a 404 for the session is returned as an error; no new initialize".
HTTPTransport.Send (internal/mcpclient/http.go ~L166-180) returns any non-2xx as HTTPStatusError; the session id is captured at ~L157-160 and echoed by setHeaders.
Register TR-29 (docs/compare/register/transports.md:550-565): legacy spec 2025-03-26..2025-11-25 — a client receiving 404 for a session-carrying request MUST start a new session; mcpx @05c78b2 missing; "a restarted remote server leaves its mcpx instance failing every call" (the pool cannot reap an HTTP client that never dies).
Decision recorded on Design: mcpx client session & stream recovery — re-initialize on a legacy session 404, re-issue a broken modern request once #1634: recovery lives in the client, not the transport (protocol-free layer) and not the pool (reaping loses the in-flight call).

Acceptance

Fake legacy HTTP upstream test: session dropped upstream → the call succeeds after exactly one re-initialize, and the retried request carries the new session id.
N concurrent calls 404ing from the same restart → exactly one initialize observed upstream.
404 with no session held (stateless legacy server) → error as today, no initialize sent.
A second 404 after re-initialize → error surfaces; no further re-initialize for that call.
Modern-era 404 → no recovery attempt.
Gap streamable-http-client-reinit-on-404 retired; go test ./... for pkgs/mcpx passes in CI.

Out of scope

Modern broken-stream re-issue (Phase 2), register truth-up (Phase 3), persisting the new session into #1414's store (open question on #1634), notification-triggered lazy re-initialize (open question on #1634).

CODE-656

agent-note:v1 — triage verdict: CONFIRMED, scope as-built verified (queue task 1770, lane A, 2026-10-28)

Verified fresh on main ed8e591 (laptop primary clone, matching the issue's evidence base):

Gap present: internal/conformance/coverage_transport.go:115 — streamable-http-client-reinit-on-404 ("a 404 for the session is returned as an error; no new initialize", origin mcpx client: legacy Streamable HTTP and stdio robustness — session 404, GET stream, SSE retry, string ids, stream timeout, version header dezren39/darwin-nix#203).
internal/mcpclient/http.go: sessionID held at :31, captured from responses at :158, non-2xx returned as HTTPStatusError at :169 (type at :690) — the trigger surface exists exactly as scoped.
Seam pattern present: client.go:377 interface-asserts interface{ setNegotiated(string) } (impl http.go:79) — the forgetSession() bool seam follows it directly; stdio transports simply won't implement it.
Recovery path present: initializeLegacy client.go:343 / finishLegacy :362, request path call :902 / roundTrip :953, client mutex mu sync.Mutex client.go:78, catalogue invalidation invalidate client.go:744 → Notifications.OnListChanged — all reusable unchanged, as the design (Design: mcpx client session & stream recovery — re-initialize on a legacy session 404, re-issue a broken modern request once #1634) requires.
No session generation exists today (only protocol-era wording) — it is new, added by the implementation.

Shapes settled by this triage:

Seam: forgetSession() bool on HTTPTransport — atomically reports whether a session id was held and clears it (plus the negotiated state tied to it), so the fresh initialize goes out with no session id and no later request echoes the dead one.
Generation: a client-side uint64 counter incremented on each successful legacy initialize; a call captures the generation before its request, and on a qualifying 404 takes the recovery mutex — if the generation has already advanced, it skips re-initialize and just retries once on the new session; otherwise it forgets, re-initializes (advancing the generation), invalidates tools/resources/prompts, and retries once.
Trigger stays exactly as scoped: request only (not notification, not initialize), HTTPStatusError 404, legacy era, and the failed request carried a session id.

Follow-up: implementation packet enqueued as a separate queue task (small_fix) with #1637's acceptance criteria intact. This triage does not implement.

🤖 Agent note · parked

Agent: queue worker (repo-worker-code), lane C shift
Session / ID: queue task 1777
Found via: queue claim (resume from parked state)
Task: PR feat(mcpx): re-initialize on a legacy session 404 and retry once (#1637) #1642 (head 5407a41) revalidated fresh: MERGEABLE, no hard-stop labels, mcpx test + nix ci + spec parity + most conformance jobs SUCCESS, zero failures. Three mcpx-conformance jobs (server-2025-03-26, server-2025-06-18, client-2026-07-28) were still queued/in-progress after the 5-minute poll window, so the task is re-parked for 20 minutes rather than held waiting on CI.
Expectation: resume = merge PR feat(mcpx): re-initialize on a legacy session 404 and retry once (#1637) #1642 when the remaining conformance jobs finish green, then complete task 1777.
Links: PR feat(mcpx): re-initialize on a legacy session 404 and retry once (#1637) #1642 · branch queue/1777-1637-legacy-reinit

🤖 Agent note · picked up

Agent: queue worker (repo-worker-code), lane C shift
Session / ID: queue task 1777 (resume of parked awaiting_ci state)
Found via: queue claim
Task: Resume PR feat(mcpx): re-initialize on a legacy session 404 and retry once (#1637) #1642 (legacy session-404 re-initialize for mcpx: Phase 1 of #1634 — re-initialize on a legacy session 404 and retry the request once #1637) on head 5407a41: verify the 3 outstanding mcpx-conformance jobs, merge if green, complete task.
Expectation: effort s — done = PR merged, issue closed, task completed.
Links: PR feat(mcpx): re-initialize on a legacy session 404 and retry once (#1637) #1642 · branch queue/1777-1637-legacy-reinit @ 5407a41

Merge pull request #1642 from developing-today/queue/1777-1637-legacy…

🤖 Agent note · done

Agent: queue worker (repo-worker-code), lane C shift
Session / ID: queue task 1777
Found via: queue claim (resume of awaiting_ci)
Task: PR feat(mcpx): re-initialize on a legacy session 404 and retry once (#1637) #1642 MERGED (merge commit 8c8d1bb); issue closed by the merge. Final CI on head 5407a41: 15 pass / 0 fail / 0 pending, including the mcpx conformance jobs server-2025-03-26, server-2025-06-18, client-2026-07-28. Legacy session-404 recovery now lives in the client (forgetSession seam + singleflight re-initialize + one retry); conformance gap streamable-http-client-reinit-on-404 retired as covered.
Expectation: done — task 1777 completed with outcome fixed_merged.
Links: PR feat(mcpx): re-initialize on a legacy session 404 and retry once (#1637) #1642

docs(mcpx): register truth-up TR-29 / PM-06 as-built + roadmap row (#…

Navigation Menu

Repository navigation

mcpx: Phase 1 of #1634 — re-initialize on a legacy session 404 and retry the request once #1637

Scope

Evidence (main `ed8e591`, 2026-10-28)

Acceptance

Out of scope

137 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

mcpx: Phase 1 of #1634 — re-initialize on a legacy session 404 and retry the request once #1637

Description

Scope

Evidence (main ed8e591, 2026-10-28)

Acceptance

Out of scope

Activity

developing-today commented on Oct 28, 2026

dezren39 commented on Oct 28, 2026

137 remaining items

dezren39 commented on Oct 28, 2026

dezren39 commented on Oct 28, 2026

dezren39 commented on Oct 28, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Evidence (main `ed8e591`, 2026-10-28)