Add tests for stateful session lifecycle and event-driven step wait

Cover the three reliability/perf fixes that the existing suite missed:

- debugMCPServer.security.test.ts: a "Streamable-HTTP session lifecycle"
  suite that drives the real handshake — initialize over POST mints an
  mcp-session-id, GET /mcp with that id returns a live text/event-stream
  (the regression that left Cursor flagging the server "errored"), and
  GET /mcp with a missing/unknown session is rejected with 400.

- debuggingHandler.test.ts: waitForStateChange tests (via handleStepOver)
  asserting the fast-path resolves in ms when the new line is already
  observable or the session ended, and that the bounded timeout (not a
  blind 1s sleep) governs the no-change case.

Author: ksa-real

src/test/debugMCPServer.security.test.ts

@@ -169,4 +169,128 @@ suite('DebugMCPServer security', () => {
             }
         });
     });
+
+    // Stateful Streamable-HTTP session lifecycle. Regression guard for the bug
+    // where the transport ran stateless and GET /mcp returned 404, so clients
+    // (Cursor) could never open the server->client SSE stream and tombstoned the
+    // connection as "errored". Here we drive the real handshake: initialize over
+    // POST mints a session id, and GET /mcp with that id must return a live
+    // text/event-stream.
+    suite('Streamable-HTTP session lifecycle', () => {
+        const port = 30100;
+        let server: DebugMCPServer;
+
+        suiteSetup(async () => {
+            server = new DebugMCPServer(port, 60);
+            await server.initialize();
+            await server.start();
+        });
+
+        suiteTeardown(async () => {
+            await server.stop();
+        });
+
+        // POST an `initialize` request and resolve with the response status plus
+        // the mcp-session-id header the server assigns to the new session.
+        function postInitialize(): Promise<{ status: number; sessionId?: string }> {
+            const body = JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2025-06-18',
+                    capabilities: {},
+                    clientInfo: { name: 'lifecycle-test', version: '0.0.0' }
+                }
+            });
+            const opts: http.RequestOptions = {
+                host: '127.0.0.1',
+                port,
+                path: '/mcp',
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json, text/event-stream',
+                    'Content-Length': Buffer.byteLength(body).toString(),
+                    'Host': `127.0.0.1:${port}`
+                }
+            };
+            return new Promise((resolve, reject) => {
+                const req = http.request(opts, res => {
+                    const sessionId = res.headers['mcp-session-id'] as string | undefined;
+                    // Drain so the socket is released; we only need status + id.
+                    res.on('data', () => { /* discard */ });
+                    res.on('end', () => resolve({ status: res.statusCode || 0, sessionId }));
+                    // initialize responds on an SSE channel that may stay open; the
+                    // headers (and session id) are already available, so resolve now
+                    // and let the drain handler clean up.
+                    resolve({ status: res.statusCode || 0, sessionId });
+                });
+                req.on('error', reject);
+                req.write(body);
+                req.end();
+            });
+        }
+
+        // Open GET /mcp (the server->client SSE stream) and resolve with the
+        // status + content-type as soon as the response headers arrive, then
+        // tear down the long-lived stream.
+        function getMcp(headers: http.OutgoingHttpHeaders): Promise<{ status: number; contentType?: string }> {
+            const opts: http.RequestOptions = {
+                host: '127.0.0.1',
+                port,
+                path: '/mcp',
+                method: 'GET',
+                headers: {
+                    'Accept': 'text/event-stream',
+                    'Host': `127.0.0.1:${port}`,
+                    ...headers
+                }
+            };
+            return new Promise((resolve, reject) => {
+                const req = http.request(opts, res => {
+                    const contentType = res.headers['content-type'];
+                    resolve({ status: res.statusCode || 0, contentType });
+                    req.destroy(); // close the long-lived SSE stream
+                });
+                req.on('error', err => {
+                    // A destroy() after we resolved can surface as ECONNRESET; ignore.
+                    if ((err as NodeJS.ErrnoException).code === 'ECONNRESET') {
+                        return;
+                    }
+                    reject(err);
+                });
+                req.end();
+            });
+        }
+
+        test('initialize over POST mints an mcp-session-id', async () => {
+            const res = await postInitialize();
+            assert.strictEqual(res.status, 200, `initialize should succeed, got ${res.status}`);
+            assert.ok(res.sessionId, 'server did not return an mcp-session-id header on initialize');
+        });
+
+        test('GET /mcp with a valid session opens a text/event-stream', async () => {
+            const init = await postInitialize();
+            assert.ok(init.sessionId, 'precondition: initialize must yield a session id');
+
+            const res = await getMcp({ 'mcp-session-id': init.sessionId });
+            assert.strictEqual(res.status, 200, `GET /mcp should open the SSE stream (200), got ${res.status}`);
+            assert.match(
+                res.contentType || '',
+                /text\/event-stream/,
+                `GET /mcp must serve an SSE stream, got content-type: ${res.contentType}`
+            );
+        });
+
+        test('GET /mcp without a session id is rejected (400)', async () => {
+            const res = await getMcp({});
+            assert.strictEqual(res.status, 400, `GET /mcp with no session must be 400, got ${res.status}`);
+        });
+
+        test('GET /mcp with an unknown session id is rejected (400)', async () => {
+            const res = await getMcp({ 'mcp-session-id': 'does-not-exist' });
+            assert.strictEqual(res.status, 400, `GET /mcp with bogus session must be 400, got ${res.status}`);
+        });
+    });
 });

src/test/debuggingHandler.test.ts

@@ -3,6 +3,7 @@
 import * as assert from 'assert';
 import { DebugState } from '../debugState';
 import { DebuggingHandler } from '../debuggingHandler';
+import { IDebuggingExecutor } from '../debuggingExecutor';
 
 /**
  * Test suite for DebuggingHandler state change detection
@@ -106,3 +107,99 @@ suite('DebuggingHandler State Change Detection', () => {
         assert.strictEqual(hasStateChanged, true);
     });
 });
+
+/**
+ * Tests for the event-driven waitForStateChange (exercised via handleStepOver).
+ *
+ * The previous implementation blind-slept ~1s per step regardless of when the
+ * stop actually landed. The current one resolves the moment the new state is
+ * observable (fast-path) or the session ends, and only falls back to the
+ * configured timeout when nothing changes. These tests drive that logic through
+ * the injected executor's getCurrentDebugState — the real vscode.debug events
+ * can't be fired from a unit test, but the fast-path and timeout branches both
+ * funnel through the executor, which is what we assert on here.
+ */
+suite('DebuggingHandler waitForStateChange (event-driven)', () => {
+
+    function lineState(line: number, active = true): DebugState {
+        const s = new DebugState();
+        s.sessionActive = active;
+        if (active) {
+            s.updateLocation('/test/file.js', 'file.js', line, `let v = ${line};`, []);
+            s.updateContext(1, 1);
+            s.updateFrameName('main');
+        }
+        return s;
+    }
+
+    // Minimal executor whose getCurrentDebugState is driven by a per-call
+    // function (call index is 0-based). All other methods are inert.
+    function makeExecutor(getState: (call: number) => DebugState): IDebuggingExecutor {
+        let call = 0;
+        return {
+            startDebugging: async () => true,
+            debugTestAtCursor: async () => ({ started: true, runComplete: new Promise<void>(() => { /* pending */ }) }),
+            stopDebugging: async () => { /* noop */ },
+            stepOver: async () => { /* noop */ },
+            stepInto: async () => { /* noop */ },
+            stepOut: async () => { /* noop */ },
+            continue: async () => { /* noop */ },
+            restart: async () => { /* noop */ },
+            addBreakpoint: async () => { /* noop */ },
+            removeBreakpoint: async () => { /* noop */ },
+            getCurrentDebugState: async () => getState(call++),
+            getVariables: async () => ({}),
+            evaluateExpression: async () => ({}),
+            getBreakpoints: () => [],
+            clearAllBreakpoints: () => { /* noop */ },
+            hasActiveSession: async () => true,
+            getActiveSession: () => undefined,
+            waitForDebugSessionReady: async () => 'no-session'
+        };
+    }
+
+    test('fast-path: resolves immediately when the new line is already observable', async () => {
+        // call 0 = before (line 10); subsequent calls = after (line 11).
+        const executor = makeExecutor(call => (call === 0 ? lineState(10) : lineState(11)));
+        // Large timeout: if this resolved via the timer instead of the fast
+        // path, the test would take 30s and the latency assertion would fail.
+        const handler = new DebuggingHandler(executor, {} as any, 30);
+
+        const started = Date.now();
+        const result = await handler.handleStepOver();
+        const elapsed = Date.now() - started;
+
+        assert.match(result, /"currentLine": 11/, `expected to land on line 11, got: ${result}`);
+        assert.ok(elapsed < 2000, `fast-path should resolve in ms, took ${elapsed}ms (did it wait for the timeout?)`);
+    });
+
+    test('fast-path: resolves immediately when the session has ended', async () => {
+        // call 0 = active (line 10); subsequent calls = session inactive.
+        const executor = makeExecutor(call => (call === 0 ? lineState(10) : lineState(0, false)));
+        const handler = new DebuggingHandler(executor, {} as any, 30);
+
+        const started = Date.now();
+        const result = await handler.handleStepOver();
+        const elapsed = Date.now() - started;
+
+        assert.match(result, /"sessionActive": false/, `expected an inactive session, got: ${result}`);
+        assert.ok(elapsed < 2000, `termination should resolve in ms, took ${elapsed}ms`);
+    });
+
+    test('timeout: falls back to the bounded timeout when nothing changes', async () => {
+        // Every call reports the same active line — no change, no event.
+        const executor = makeExecutor(() => lineState(10));
+        // 0.3s timeout so the fallback path is quick to exercise.
+        const handler = new DebuggingHandler(executor, {} as any, 0.3);
+
+        const started = Date.now();
+        const result = await handler.handleStepOver();
+        const elapsed = Date.now() - started;
+
+        assert.match(result, /"currentLine": 10/, `expected to stay on line 10, got: ${result}`);
+        // Must actually wait out the timer (not settle spuriously) but still be
+        // bounded by it (not hang).
+        assert.ok(elapsed >= 200, `should wait for the ~300ms timeout, only took ${elapsed}ms`);
+        assert.ok(elapsed < 3000, `timeout should bound the wait, took ${elapsed}ms`);
+    });
+});