[debugmcpdev]

Updated 2026-11-10 (second look: commits d34e5c73, 46e0d205). Two things said below no longer hold: the idle policy is off by default on every transport (not "30 min on http"), and a session outside the caller's scope is no longer answered by the dispatch with one fixed sentence — it is hidden from the call and each tool answers as it answers an unknown id. See "Second look" at the end.

Summary

PR 2 of 5 for #1025 step 2 (plan and decisions on the issue). Stacked on #1114 (PR 1); the base retargets to main when that merges. Three commits, each green on its own:

1. The owner-key seam. Ownership stays server-side — the handle is the capability — but the seam for real isolation exists now: a debug session is created in its caller's scope (the authenticated principal when the request carried authInfo, otherwise the shared anonymous scope), a child inherits its root's scope, and list_debug_sessions, resources/list, resources/read, resources/subscribe and the tools/call dispatch answer only within the caller's scope. An out-of-scope id answers exactly as an unknown id (no existence leak). With no authentication in front of the server every caller is anonymous and sees everything, which is today's single-tenant behaviour. The http: a debug session owned by another MCP client session answers a plain Session not found; say that sessions are per client #939 foreign-session refusal goes with it: with one core per process there is no "other server", only scopes.
2. The per-debug-session idle policy. A tree whose root has seen no tool call for MCP_DEBUG_SESSION_IDLE_MS (default 30 min on http, 0 = off on stdio; 0 disables) is closed through the normal close cascade. Only roots have a clock; a tool call naming any session in a tree refreshes its root; an in-flight wait_for_stop holds the root; children never expire on a clock of their own; and the sweep (MCP_DEBUG_SESSION_IDLE_SWEEP_MS, 60 s) is skipped entirely while a client is attending the process.
3. One core per http process. The app builds one DebugMcpServer after the refusal gates and starts it once; every MCP session is a legacy-era facade over it. An MCP session is a connection: its close, reap or DELETE /mcp forgets the connection and nothing else; the debug sessions it created answer to the idle policy. "Attended" = any MCP session holds an SSE stream open. /health gains attended, listenStreams and the process's debugSessions (with idle time); the reaper lines lose the "holding debug session(s)" suffix; a transport whose initialize the SDK refused is closed at once; shutdown closes every transport, then the one core.

Decisions carried (JF, 2026-11-07 and 2026-11-09)

Idle policy only (no stream-lost accelerator); idle off on stdio; the #939 isolation dropped in both eras with the owner-key seam built now; expiry suspended while the process is attended; children go with their root. The session-tree design doc's ownership-and-lifetime section is amended accordingly (root-only clocks; attended suspension).

Measured

The attendance premise the "suspend while attended" rule rests on: tests/integration/cli/http-shared-core.test.ts connects a v2 SDK client in legacy mode, makes no tool call, and reads /health.attended === true for the life of the connection and false once it closes. Green on this box.

Tests

• New: owner-key.test.ts, session-owner-key.test.ts, tool-dispatch-owner-key.test.ts (replaces the http: a debug session owned by another MCP client session answers a plain Session not found; say that sessions are per client #939 gate suite), session-idle-policy.test.ts (11 cases: expiry, root refresh through a child, children never alone, cascade, holds, attended, 0, no clock left behind), idle cases in server-lifecycle.test.ts (timer, env knobs, supplier, a rejecting sweep), hold cases in execution-tools.test.ts, http-shared-core.test.ts (replaces http-foreign-session.test.ts).
• http-command.test.ts: one core after the gates, started once; /health re-pinned; close/reap leave the core running; refused-initialize close; shutdown stops the core once after the transports; the transport mock now completes an initialize inside handleRequest, as the SDK does.
• mcp-server-smoke-http-stale-reap.test.ts sets the idle knobs and watches Closing idle debug session after Reaping stale HTTP session.
• Gates locally: typecheck:all 0 (ratchet 0/0), lint, check-docs, changelog, unit 415 files / 8258 passed, integration tests/integration/cli/ + self-debug 41/41, e2e stale-reap + HTTP smoke 3/3, conformance 7/7 (0.1.16, unchanged — the 2025-11-25 wire is untouched).

Review follow-ups (fourth commit)

A fresh-context review found no critical issue and three to fix, all in: a finished wait_for_stop now counts as activity (the idle clock restarts when it settles, not when it was asked); the attendance measurement reads /health again 2.5 s after the first attended: true and asserts the stream is still held (openStreams: 1), so a flicker could not pass it; the docs no longer suggest a reverse proxy in front of /mcp scopes sessions per principal — the seam exists in the server, but no authenticated http mode ships yet and every caller shares one scope. Also hardened on the same pass: a transport whose handshake threw is closed in finally (no orphaned facade sink); a child adoption refreshes its root's idle clock; a stray sessionId on a tool whose schema takes none refreshes nothing; the sweep asks the attended supplier again before each close; one attendance predicate feeds both the supplier and /health; the refused-initialize unit test asserts the clean path (no 500, no error log); the ownership fragment names the removed details[].debugSessions field. Deferred (noted on the issue for the authenticated-mode follow-up): a failed listen exits without core.stop() (cosmetic), and the owner-key dispatch suite drives the handler with a hand-built request context rather than a real SDK Server.

Notes

• The ten-per-language adapter cap is per process now, as it always was on stdio.
• After merge: file "authenticated http mode" (bearer verification in front of /mcp, the SDK's requireBearerAuth, non-loopback binding guidance) as the path that turns the seam into real multi-tenant isolation; per-principal attendance belongs there too.
• Next: PR 3 (the modern era on stdio through serveStdio).

Second look (commits d34e5c73, 46e0d205)

JF asked whether the rulings I made on his behalf while building step 2 were sound. Two on this PR were not, and one decision was re-opened and changed.

Idle expiry is off by default (JF's decision, 2026-11-10). The 30-minute default came from the old MCP-session reaper (#337), where an open stream protected a client. A 2026 tools-only client has no stream, so the default would have ended the program of any agent that went quiet for half an hour — one busy elsewhere, or waiting on a human. A sessionless client gives the server no sign of life between calls, so any finite default has that false positive, and it is destructive, while a leaked session is visible and closable. Now nothing expires unless MCP_DEBUG_SESSION_IDLE_MS is set; the per-transport default plumbing is gone and the start-up log says which rule is in force. The Kubernetes and jit-diagnostics recipes set the knob in their command lines (5 minutes), because an attach to a production pod must not rely on a default.

When the policy is on, the agent can see it. list_debug_sessions rows carry idleMs (and expiresInMs); the server instructions state the window; and a tool call naming a session the policy closed answers when, under which window, and whether its program was ended or released (closedBy: "idle-policy") where it used to answer "Session not found" — the words a mistyped id gets. The adapter-cap refusal, where forgotten sessions now surface, says how to find and close them.

The owner-key gate leaked what it exists to hide. It answered a session outside the caller's scope with one fixed sentence, which differed from the real unknown-id answer of nine tools (close_debug_session, start_debugging, attach_to_process, detach_from_process, hot_reload, set_breakpoint, remove_breakpoint, get_local_variables, evaluate_expression) and in the operator log: a caller could tell "exists, not mine" from "does not exist". The dispatch now runs a tool that takes a sessionId with that session hidden from the store's lookups (src/session/session-scope.ts, AsyncLocalStorage), so each tool gives its own unknown-id answer by construction. owner-scope-contract.test.ts holds it over the real SessionManager and store: every such tool and alias, four argument shapes, two session states, asked by another principal and by an anonymous caller, plus the listings and resources — 458 cases. Dormant until an authenticated mode exists, as before.

Review of this pass. A fresh-context review reproduced a regression in my first version of that fix: it entered the hidden scope for tools that take no sessionId too, and list_debug_sessions then read owner keys through the hidden lookup, so an anonymous caller passing a foreign id as a stray argument was shown that session's row. Fixed in 46e0d205 (the scope only for tools that take the id; the listing reads owner keys off the managed rows), with the contract test widened to the cases that would have caught it.

Not scoped, stated in the design doc: a 2026-07-28 subscriptions/listen and GET /health. The SDK's entry serves listen and publishes by URI with no hook that sees the listener, and its acknowledgement echoes the honoured filter, so dropping a foreign URI at request time would itself tell it from an unknown one. Both are acceptance criteria of the authenticated-http issue.

Verified: typecheck:all, lint, check-docs, changelog; pre-push hook unit 417 files / 8737 tests, integration 33 files / 161 tests.

CI on this branch head (dispatched by hand: the workflow triggers on PRs to main only, so a stacked PR gets no automatic run and gh pr checks shows nothing): https://github.com/debugmcp/mcp-debugger/actions/runs/42879516734 (head 46e0d205, 11 of 11 jobs green)

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 96.91120% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/cli/http-command.ts	93.10%	2 Missing ⚠️
src/session/idle-policy.ts	92.30%	2 Missing ⚠️
src/session/session-manager-core.ts	97.95%	2 Missing ⚠️
src/server.ts	96.15%	1 Missing ⚠️
src/server/tool-dispatch.ts	97.43%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[debugmcpdev]

Review found that idle expiry copied a launch root's 'ended' outcome onto JavaScript children that had actually been released. Fixed in 91a7e7f: the close cascade records per-session release outcomes, and regressions cover both mixed outcomes and natural termination during an earlier child's close. The original defect and a stale-snapshot race were reproduced; five focused production-method scenarios now pass, and the fix received a second independent review. Full CI on the updated branch remains required before merge. The fix has been propagated through the descendant PRs while preserving the stack.

[debugmcpdev]

Follow-up validation with this fix propagated to the top stack head 9e948b8: all 22 idle-policy and 71 child-session tests pass, including the new mixed-outcome and termination-during-cascade regressions. typecheck:all reports zero source/test errors and the changed production file passes ESLint. No validation-only source or lockfile changes were made. Fresh current-base GitHub CI remains required before merge.

[debugmcpdev]

Follow-up security review: the current-main CodeQL scan found raw rejected environment values being copied into idle-policy warnings. Commit f133870 removes those contents while retaining the setting name and fallback value. Added regression cases for both settings using synthetic secret-like multiline input. Both regressions failed before the fix; all 25 lifecycle and idle-answer tests pass after it, with type checks and lint clean. Independently reviewed the exact two-file change. The fresh CodeQL security gate now passes with no new alerts. Remaining CI must finish before merging.