@testdriverai/mcp 7.11.10-canary → 7.11.11-canary

package/mcp-server/dist/core/actions.d.ts

@@ -58,7 +58,29 @@ export declare class NoActiveSessionError extends Error {
  * per async call via {@link als}.
  */
 export interface CoreContext {
+    /**
+     * The live SDK handle. Only ever assigned once its `connect()` has resolved —
+     * see {@link sdkGeneration}. Readers may assume `sdk.connected === true`.
+     */
     sdk: any;
+    /**
+     * Monotonic epoch, bumped by every flow that starts building a new SDK
+     * (`sessionStart` / `reconnectSession`).
+     *
+     * Why: a flow can be abandoned while its `connect()` is still in flight — eve's
+     * per-action deadline explicitly stops waiting on the SDK promise but cannot
+     * cancel it, so the abandoned action keeps running and races the retry that
+     * replaced it. Both then reach for `c.sdk`. Without an epoch the loser lands
+     * last and installs its (older, or half-built) SDK over the winner's, and every
+     * subsequent action fails against a connection nobody is maintaining.
+     *
+     * Each flow captures the epoch before it builds, and publishes only if the
+     * epoch is still its own. The loser closes the sandbox it built instead of
+     * leaking it — an orphaned sandbox pins a team concurrency slot for the whole
+     * keepAlive window (15 min for eve), which is what eventually starves the team
+     * and turns every later `connect()` into a slot-denial poll.
+     */
+    sdkGeneration: number;
     lastScreenshotBase64: string | null;
     reconnectResolver: ReconnectResolver | null;
     /** In-flight reconnect, so concurrent actions in one context share one rebuild. */
@@ -144,13 +166,41 @@ export declare function getElementRef(ref: string): {
     };
 } | undefined;
 /**
- * Cheap, side-effect-free check for a usable in-process session: a live SDK and
- * a current session that hasn't expired. Durable adapters call this *before*
- * doing any expensive reconnect prep (e.g. re-resolving an API key), so the
- * common warm-process path stays free. Note: unlike `requireActiveSession`, this
- * does NOT refresh the keepAlive window — it only reports liveness.
+ * Cheap, side-effect-free check for a usable in-process session: a *connected*
+ * SDK and a current session that is active and hasn't expired. Durable adapters
+ * call this *before* doing any expensive reconnect prep (e.g. re-resolving an API
+ * key), so the common warm-process path stays free. Note: unlike
+ * `requireActiveSession`, this does NOT refresh the keepAlive window — it only
+ * reports liveness.
+ *
+ * Both extra conditions matter, and neither used to be checked:
+ *
+ *  - `sdk.connected` — the SDK sets this only when `connect()` resolves, and it
+ *    is the flag `_ensureConnected()` gates every command on. A mere `!!c.sdk`
+ *    accepted an SDK whose `connect()` was still in flight, so a caller could be
+ *    told the session was live and then have the very next action throw "SDK is
+ *    not connected. Call connect() first."
+ *  - `status === "active"` — `isSessionValid()` deliberately accepts
+ *    `"initializing"` (it only rejects `expired`/`error`), so a session that was
+ *    created but never finished connecting counted as usable.
  */
 export declare function hasLiveSession(): boolean;
+/**
+ * Drop the in-process session and SDK handle after the caller has released the
+ * sandbox out-of-band (eve's `session_end`, which calls `sdk.sandbox.close()`).
+ *
+ * Without this, ending a session left the context claiming a live one: `close()`
+ * tears down the sandbox's Ably client but never clears the SDK's own `connected`
+ * flag, and the session stayed `active` in the registry pointing at a sandbox that
+ * no longer exists — so `hasLiveSession()` answered true and `session_status`
+ * reported an active session for a dead VM.
+ *
+ * Bumping the epoch is the important part: any build still in flight (an abandoned
+ * action's reconnect) now loses its publish and closes the sandbox it opened,
+ * instead of resurrecting a session the caller explicitly ended — which would
+ * silently re-take a team concurrency slot.
+ */
+export declare function clearSession(): void;
 export interface SessionStartHooks {
     /** Called before a long await; return a stop fn. Lets adapters heartbeat. */
     onProgress?: (message: string) => void;

package/mcp-server/dist/core/actions.js

@@ -39,6 +39,7 @@ export class NoActiveSessionError extends Error {
 export function createCoreContext() {
     return {
         sdk: null,
+        sdkGeneration: 0,
         lastScreenshotBase64: null,
         reconnectResolver: null,
         reconnecting: null,
@@ -110,16 +111,55 @@ export function getElementRef(ref) {
     return ctx().elementRefs.get(ref);
 }
 /**
- * Cheap, side-effect-free check for a usable in-process session: a live SDK and
- * a current session that hasn't expired. Durable adapters call this *before*
- * doing any expensive reconnect prep (e.g. re-resolving an API key), so the
- * common warm-process path stays free. Note: unlike `requireActiveSession`, this
- * does NOT refresh the keepAlive window — it only reports liveness.
+ * Cheap, side-effect-free check for a usable in-process session: a *connected*
+ * SDK and a current session that is active and hasn't expired. Durable adapters
+ * call this *before* doing any expensive reconnect prep (e.g. re-resolving an API
+ * key), so the common warm-process path stays free. Note: unlike
+ * `requireActiveSession`, this does NOT refresh the keepAlive window — it only
+ * reports liveness.
+ *
+ * Both extra conditions matter, and neither used to be checked:
+ *
+ *  - `sdk.connected` — the SDK sets this only when `connect()` resolves, and it
+ *    is the flag `_ensureConnected()` gates every command on. A mere `!!c.sdk`
+ *    accepted an SDK whose `connect()` was still in flight, so a caller could be
+ *    told the session was live and then have the very next action throw "SDK is
+ *    not connected. Call connect() first."
+ *  - `status === "active"` — `isSessionValid()` deliberately accepts
+ *    `"initializing"` (it only rejects `expired`/`error`), so a session that was
+ *    created but never finished connecting counted as usable.
  */
 export function hasLiveSession() {
     const c = ctx();
     const session = c.sessions.getCurrentSession();
-    return !!c.sdk && !!session && c.sessions.isSessionValid(session.sessionId);
+    if (!sdkIsConnected(c.sdk) || !session)
+        return false;
+    return session.status === "active" && c.sessions.isSessionValid(session.sessionId);
+}
+/**
+ * Drop the in-process session and SDK handle after the caller has released the
+ * sandbox out-of-band (eve's `session_end`, which calls `sdk.sandbox.close()`).
+ *
+ * Without this, ending a session left the context claiming a live one: `close()`
+ * tears down the sandbox's Ably client but never clears the SDK's own `connected`
+ * flag, and the session stayed `active` in the registry pointing at a sandbox that
+ * no longer exists — so `hasLiveSession()` answered true and `session_status`
+ * reported an active session for a dead VM.
+ *
+ * Bumping the epoch is the important part: any build still in flight (an abandoned
+ * action's reconnect) now loses its publish and closes the sandbox it opened,
+ * instead of resurrecting a session the caller explicitly ended — which would
+ * silently re-take a team concurrency slot.
+ */
+export function clearSession() {
+    const c = ctx();
+    const current = c.sessions.getCurrentSession();
+    if (current)
+        c.sessions.endSession(current.sessionId);
+    c.sdk = null;
+    c.lastScreenshotBase64 = null;
+    c.elementRefs.clear();
+    c.sdkGeneration++;
 }
 // =============================================================================
 // Helpers
@@ -177,12 +217,68 @@ function bareBase64(s) {
  */
 function realtimeIsHealthy(s) {
     try {
-        return s?.sandbox?._ably?.connection?.state === "connected";
+        return sdkIsConnected(s) && s?.sandbox?._ably?.connection?.state === "connected";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `s` is an SDK that has finished connecting.
+ *
+ * `connected` flips to true only at the end of `connect()` and is exactly what
+ * the SDK's own `_ensureConnected()` guards every command on, so it is the one
+ * honest answer to "can I use this handle". Checking only for the *object* let a
+ * still-connecting SDK pass as usable. Optional-chained and defensive: an
+ * unusable handle must read as not-connected rather than throw.
+ */
+function sdkIsConnected(s) {
+    try {
+        return s?.connected === true;
     }
     catch {
         return false;
     }
 }
+/**
+ * Close a sandbox we built but are not going to publish (we lost the epoch race).
+ * Best-effort, but worth awaiting: `close()` publishes `end-session` and leaves
+ * presence, which releases the team concurrency slot immediately instead of
+ * letting the orphan pin it for the full keepAlive window.
+ */
+async function discardSdk(sdk) {
+    try {
+        await sdk?.sandbox?.close?.();
+    }
+    catch {
+        /* best effort — the server reaps the orphan on lease expiry regardless */
+    }
+}
+/**
+ * Publish `sdk` as the context's handle, unless a newer flow superseded us while
+ * we were connecting. Returns false when superseded, having closed the sandbox we
+ * built so it can't linger as an orphan holding a concurrency slot.
+ *
+ * Call this immediately after `connect()` resolves and before touching `c.sdk`.
+ */
+async function publishSdk(c, sdk, generation) {
+    if (c.sdkGeneration !== generation) {
+        await discardSdk(sdk);
+        return false;
+    }
+    c.sdk = sdk;
+    return true;
+}
+/** Result for a `sessionStart` that lost the epoch race to a newer session_start. */
+function supersededResult() {
+    return {
+        ok: false,
+        text: "This session_start was superseded by a newer one that is already connected. " +
+            "The sandbox this call provisioned has been released. Use the active session, " +
+            "or call session_end and then session_start if you need a fresh sandbox.",
+        data: { action: "session_start", error: "SESSION_SUPERSEDED" },
+    };
+}
 /**
  * Attempt to rebuild the singleton from the adapter-registered recovery hook.
  * Returns true if a usable session now exists, false if there was nothing to
@@ -272,10 +368,17 @@ async function requireActiveSession() {
     // Reset the keepAlive timer on each command so active use doesn't expire.
     c.sessions.refreshSession(current.sessionId);
 }
-/** Capture a fresh full-screen screenshot as bare base64 (or null on failure). */
-async function captureScreen() {
+/**
+ * Capture a fresh full-screen screenshot as bare base64 (or null on failure).
+ *
+ * Pass an explicit `sdk` from any flow that owns a local handle (`sessionStart`):
+ * reading `ctx().sdk` there would let a concurrent rebuild swap the instance out
+ * between provisioning and the screenshot. Actions that have already been through
+ * `requireActiveSession()` can omit it — the context's SDK is the right one.
+ */
+async function captureScreen(sdk = ctx().sdk) {
     try {
-        const b64 = await ctx().sdk.agent.system.captureScreenBase64(1, false, true);
+        const b64 = await sdk.agent.system.captureScreenBase64(1, false, true);
         return b64 || null;
     }
     catch {
@@ -299,11 +402,13 @@ export async function sessionStart(params, resolved, hooks = {}) {
             return { ok: false, text: "electron type requires 'appPath' parameter", data: { error: "Missing required parameter: appPath" } };
         }
     }
-    const newSession = c.sessions.createSession({
-        os: resolved.os,
-        keepAlive: params.keepAlive,
-        testFile: params.testFile,
-    });
+    // NOTE: the session is deliberately NOT created here. `createSession()` marks
+    // the new session *current* immediately, with status "initializing" — and
+    // `isSessionValid()` accepts that status — so creating it before `connect()`
+    // published a half-real session to every concurrent reader, and a `connect()`
+    // that threw or stalled (e.g. polling for a free concurrency slot) left it
+    // current forever. That is the `session_status: initializing` that never
+    // resolves. We create and activate it below, only once we have a live sandbox.
     const apiRoot = params.apiRoot || process.env.TD_API_ROOT || "https://api.testdriver.ai";
     const previewMode = process.env.TD_PREVIEW || "ide";
     const instanceIp = params.ip || process.env.TD_IP;
@@ -323,8 +428,16 @@ export async function sessionStart(params, resolved, hooks = {}) {
             },
         };
     }
+    // Build into a LOCAL handle and publish to `c.sdk` only once `connect()` has
+    // resolved. Assigning `c.sdk` up front exposed an SDK whose `connected` flag is
+    // still false to every concurrent reader, and — because each step below used to
+    // re-read `c.sdk` — let a concurrent rebuild swap the instance out *between*
+    // connect and provision, so provisioning ran against a handle that had never
+    // been connected and threw "SDK is not connected. Call connect() first."
+    // Everything below uses `sdk`; `c.sdk` is written exactly once, at publish.
+    const generation = ++c.sdkGeneration;
     const TestDriverSDK = (await loadTestDriverSdk()).default;
-    c.sdk = new TestDriverSDK(apiKey, {
+    const sdk = new TestDriverSDK(apiKey, {
         os: resolved.os,
         logging: false,
         apiRoot,
@@ -335,11 +448,18 @@ export async function sessionStart(params, resolved, hooks = {}) {
     // Debug mode — attach to an existing sandbox, skip provisioning.
     if (params.sandboxId) {
         progress(`Connecting to existing sandbox ${params.sandboxId}...`);
-        await c.sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
-        const instance = c.sdk.getInstance();
+        await sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
+        if (!(await publishSdk(c, sdk, generation)))
+            return supersededResult();
+        const instance = sdk.getInstance();
+        const newSession = c.sessions.createSession({
+            os: resolved.os,
+            keepAlive: params.keepAlive,
+            testFile: params.testFile,
+        });
         c.sessions.activateSession(newSession.sessionId, instance?.instanceId || params.sandboxId);
         progress("Capturing screenshot...");
-        const shot = await captureScreen();
+        const shot = await captureScreen(sdk);
         if (shot)
             c.lastScreenshotBase64 = shot;
         return {
@@ -351,36 +471,43 @@ export async function sessionStart(params, resolved, hooks = {}) {
         };
     }
     progress(instanceIp ? `Connecting to self-hosted instance ${instanceIp}...` : "Connecting to cloud sandbox...");
-    await c.sdk.connect({ reconnect: params.reconnect, keepAlive: params.keepAlive, ip: instanceIp });
-    const instance = c.sdk.getInstance();
+    await sdk.connect({ reconnect: params.reconnect, keepAlive: params.keepAlive, ip: instanceIp });
+    if (!(await publishSdk(c, sdk, generation)))
+        return supersededResult();
+    const instance = sdk.getInstance();
+    const newSession = c.sessions.createSession({
+        os: resolved.os,
+        keepAlive: params.keepAlive,
+        testFile: params.testFile,
+    });
     c.sessions.activateSession(newSession.sessionId, instance?.instanceId || "unknown");
     const provisionOptions = getProvisionOptions(params);
     let provisionCmd = "";
     progress(`Provisioning ${params.type}...`);
     switch (params.type) {
         case "chrome":
-            await c.sdk.provision.chrome(provisionOptions);
+            await sdk.provision.chrome(provisionOptions);
             provisionCmd = "provision.chrome";
             break;
         case "chromeExtension":
-            await c.sdk.provision.chromeExtension(provisionOptions);
+            await sdk.provision.chromeExtension(provisionOptions);
             provisionCmd = "provision.chromeExtension";
             break;
         case "vscode":
-            await c.sdk.provision.vscode(provisionOptions);
+            await sdk.provision.vscode(provisionOptions);
             provisionCmd = "provision.vscode";
             break;
         case "installer":
-            await c.sdk.provision.installer(provisionOptions);
+            await sdk.provision.installer(provisionOptions);
             provisionCmd = "provision.installer";
             break;
         case "electron":
-            await c.sdk.provision.electron(provisionOptions);
+            await sdk.provision.electron(provisionOptions);
             provisionCmd = "provision.electron";
             break;
     }
     progress("Capturing screenshot...");
-    const shot = await captureScreen();
+    const shot = await captureScreen(sdk);
     if (shot)
         c.lastScreenshotBase64 = shot;
     const debuggerUrl = instance?.debuggerUrl || (instanceIp ? `http://${instanceIp}:9222` : null);
@@ -422,13 +549,14 @@ export async function reconnectSession(params) {
     const c = ctx();
     const apiRoot = params.apiRoot || process.env.TD_API_ROOT || "https://api.testdriver.ai";
     const previewMode = process.env.TD_PREVIEW || "ide";
-    const session = c.sessions.createSession({
-        os: params.os,
-        keepAlive: params.keepAlive,
-        testFile: params.testFile,
-    });
+    // Local handle + epoch, published only after connect() — see sessionStart and
+    // CoreContext.sdkGeneration. This path is the one an abandoned action reaches
+    // (eve stops waiting on a slow action but cannot cancel it, so the zombie keeps
+    // running and calls in here), which is exactly how a stale rebuild used to land
+    // on top of a newer, healthy SDK.
+    const generation = ++c.sdkGeneration;
     const TestDriverSDK = (await loadTestDriverSdk()).default;
-    c.sdk = new TestDriverSDK(params.apiKey, {
+    const sdk = new TestDriverSDK(params.apiKey, {
         os: params.os,
         logging: false,
         apiRoot,
@@ -436,8 +564,23 @@ export async function reconnectSession(params) {
         ip: params.ip,
         e2bTemplateId: params.e2bTemplateId,
     });
-    await c.sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
-    const instance = c.sdk.getInstance();
+    await sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
+    // Superseded: a newer rebuild already published a live SDK. Release the sandbox
+    // we just attached (`publishSdk` closes it) and hand back the winner's session
+    // rather than clobbering it. The session is only created on the winning path, so
+    // a loser never leaves a stray "initializing" session current.
+    if (!(await publishSdk(c, sdk, generation))) {
+        const current = c.sessions.getCurrentSession();
+        if (current && c.sessions.isSessionValid(current.sessionId))
+            return current.sessionId;
+        throw new NoActiveSessionError("SESSION_EXPIRED", "The sandbox connection was superseded and no active session remains. Call session_start again to create a new sandbox session.");
+    }
+    const session = c.sessions.createSession({
+        os: params.os,
+        keepAlive: params.keepAlive,
+        testFile: params.testFile,
+    });
+    const instance = sdk.getInstance();
     c.sessions.activateSession(session.sessionId, instance?.instanceId || params.sandboxId);
     return session.sessionId;
 }

package/mcp-server/src/core/actions.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Unit tests for the session-liveness predicate.
+ *
+ * Regression cover for the "SDK is not connected. Call connect() first." cascade:
+ * `hasLiveSession()` used to answer `!!c.sdk && session valid`, which accepted
+ *   - an SDK whose `connect()` was still in flight (`connected === false`), and
+ *   - a session still in its `initializing` status (`isSessionValid()` only
+ *     rejects `expired`/`error`).
+ *
+ * Both are reachable whenever a rebuild is racing an in-flight action, and either
+ * one made eve's `session_start` take its warm no-op path over a connection that
+ * could not serve a single command.
+ */
+
+import { describe, it, expect } from "vitest";
+import { clearSession, createIsolatedContext, hasLiveSession, runInContext, type CoreContext } from "./actions.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** A context holding `sdk`, with a session that is active unless told otherwise. */
+function contextWith(sdk: unknown, opts: { activate?: boolean } = {}): CoreContext {
+  const c = createIsolatedContext();
+  c.sdk = sdk;
+  const session = c.sessions.createSession({ os: "linux", keepAlive: 60_000 });
+  if (opts.activate !== false) c.sessions.activateSession(session.sessionId, "sb-test");
+  return c;
+}
+
+const live = (c: CoreContext) => runInContext(c, () => hasLiveSession());
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("hasLiveSession", () => {
+  it("accepts a connected SDK on an active session", () => {
+    expect(live(contextWith({ connected: true }))).toBe(true);
+  });
+
+  it("rejects an SDK whose connect() has not resolved yet", () => {
+    // The half-built handle: the object exists, so the old `!!c.sdk` said "live",
+    // but every command would throw from _ensureConnected().
+    expect(live(contextWith({ connected: false }))).toBe(false);
+  });
+
+  it("rejects a session that was created but never activated", () => {
+    // status stays "initializing" — which isSessionValid() deliberately accepts.
+    expect(live(contextWith({ connected: true }, { activate: false }))).toBe(false);
+  });
+
+  it("rejects when there is no SDK at all", () => {
+    expect(live(contextWith(null))).toBe(false);
+  });
+
+  it("rejects an expired session even with a connected SDK", () => {
+    const c = createIsolatedContext();
+    c.sdk = { connected: true };
+    const session = c.sessions.createSession({ os: "linux", keepAlive: -1 });
+    c.sessions.activateSession(session.sessionId, "sb-test");
+    expect(live(c)).toBe(false);
+  });
+
+  it("does not throw on a hostile/exotic sdk handle", () => {
+    // The predicate must fail safe (unusable → "not live"), never propagate.
+    const hostile = {
+      get connected(): boolean {
+        throw new Error("boom");
+      },
+    };
+    expect(() => live(contextWith(hostile))).not.toThrow();
+    expect(live(contextWith(hostile))).toBe(false);
+  });
+});
+
+describe("clearSession", () => {
+  it("stops reporting a live session once the sandbox is released", () => {
+    // session_end's shape: sandbox.close() leaves sdk.connected true and the
+    // session 'active', so only clearSession() can make the context honest.
+    const c = contextWith({ connected: true });
+    expect(live(c)).toBe(true);
+
+    runInContext(c, () => clearSession());
+
+    expect(live(c)).toBe(false);
+    expect(c.sdk).toBeNull();
+    expect(c.sessions.getCurrentSession()).toBeNull();
+  });
+
+  it("bumps the epoch so an in-flight build can no longer publish", () => {
+    const c = contextWith({ connected: true });
+    const before = c.sdkGeneration;
+    runInContext(c, () => clearSession());
+    expect(c.sdkGeneration).toBeGreaterThan(before);
+  });
+
+  it("is safe to call with no session at all", () => {
+    const c = createIsolatedContext();
+    expect(() => runInContext(c, () => clearSession())).not.toThrow();
+    expect(live(c)).toBe(false);
+  });
+});
+
+describe("createIsolatedContext", () => {
+  it("starts at generation 0 so the first build wins its epoch", () => {
+    expect(createIsolatedContext().sdkGeneration).toBe(0);
+  });
+
+  it("gives each context its own SessionManager", () => {
+    const a = createIsolatedContext();
+    const b = createIsolatedContext();
+    a.sessions.createSession({ os: "linux", keepAlive: 60_000 });
+    expect(a.sessions.getCurrentSession()).not.toBeNull();
+    expect(b.sessions.getCurrentSession()).toBeNull();
+  });
+});

package/mcp-server/src/core/actions.ts

@@ -81,7 +81,29 @@ export class NoActiveSessionError extends Error {
  * per async call via {@link als}.
  */
 export interface CoreContext {
+  /**
+   * The live SDK handle. Only ever assigned once its `connect()` has resolved —
+   * see {@link sdkGeneration}. Readers may assume `sdk.connected === true`.
+   */
   sdk: any;
+  /**
+   * Monotonic epoch, bumped by every flow that starts building a new SDK
+   * (`sessionStart` / `reconnectSession`).
+   *
+   * Why: a flow can be abandoned while its `connect()` is still in flight — eve's
+   * per-action deadline explicitly stops waiting on the SDK promise but cannot
+   * cancel it, so the abandoned action keeps running and races the retry that
+   * replaced it. Both then reach for `c.sdk`. Without an epoch the loser lands
+   * last and installs its (older, or half-built) SDK over the winner's, and every
+   * subsequent action fails against a connection nobody is maintaining.
+   *
+   * Each flow captures the epoch before it builds, and publishes only if the
+   * epoch is still its own. The loser closes the sandbox it built instead of
+   * leaking it — an orphaned sandbox pins a team concurrency slot for the whole
+   * keepAlive window (15 min for eve), which is what eventually starves the team
+   * and turns every later `connect()` into a slot-denial poll.
+   */
+  sdkGeneration: number;
   lastScreenshotBase64: string | null;
   reconnectResolver: ReconnectResolver | null;
   /** In-flight reconnect, so concurrent actions in one context share one rebuild. */
@@ -106,6 +128,7 @@ export interface CoreContext {
 export function createCoreContext(): CoreContext {
   return {
     sdk: null,
+    sdkGeneration: 0,
     lastScreenshotBase64: null,
     reconnectResolver: null,
     reconnecting: null,
@@ -210,16 +233,54 @@ export function getElementRef(ref: string) {
 }
 
 /**
- * Cheap, side-effect-free check for a usable in-process session: a live SDK and
- * a current session that hasn't expired. Durable adapters call this *before*
- * doing any expensive reconnect prep (e.g. re-resolving an API key), so the
- * common warm-process path stays free. Note: unlike `requireActiveSession`, this
- * does NOT refresh the keepAlive window — it only reports liveness.
+ * Cheap, side-effect-free check for a usable in-process session: a *connected*
+ * SDK and a current session that is active and hasn't expired. Durable adapters
+ * call this *before* doing any expensive reconnect prep (e.g. re-resolving an API
+ * key), so the common warm-process path stays free. Note: unlike
+ * `requireActiveSession`, this does NOT refresh the keepAlive window — it only
+ * reports liveness.
+ *
+ * Both extra conditions matter, and neither used to be checked:
+ *
+ *  - `sdk.connected` — the SDK sets this only when `connect()` resolves, and it
+ *    is the flag `_ensureConnected()` gates every command on. A mere `!!c.sdk`
+ *    accepted an SDK whose `connect()` was still in flight, so a caller could be
+ *    told the session was live and then have the very next action throw "SDK is
+ *    not connected. Call connect() first."
+ *  - `status === "active"` — `isSessionValid()` deliberately accepts
+ *    `"initializing"` (it only rejects `expired`/`error`), so a session that was
+ *    created but never finished connecting counted as usable.
  */
 export function hasLiveSession(): boolean {
   const c = ctx();
   const session = c.sessions.getCurrentSession();
-  return !!c.sdk && !!session && c.sessions.isSessionValid(session.sessionId);
+  if (!sdkIsConnected(c.sdk) || !session) return false;
+  return session.status === "active" && c.sessions.isSessionValid(session.sessionId);
+}
+
+/**
+ * Drop the in-process session and SDK handle after the caller has released the
+ * sandbox out-of-band (eve's `session_end`, which calls `sdk.sandbox.close()`).
+ *
+ * Without this, ending a session left the context claiming a live one: `close()`
+ * tears down the sandbox's Ably client but never clears the SDK's own `connected`
+ * flag, and the session stayed `active` in the registry pointing at a sandbox that
+ * no longer exists — so `hasLiveSession()` answered true and `session_status`
+ * reported an active session for a dead VM.
+ *
+ * Bumping the epoch is the important part: any build still in flight (an abandoned
+ * action's reconnect) now loses its publish and closes the sandbox it opened,
+ * instead of resurrecting a session the caller explicitly ended — which would
+ * silently re-take a team concurrency slot.
+ */
+export function clearSession(): void {
+  const c = ctx();
+  const current = c.sessions.getCurrentSession();
+  if (current) c.sessions.endSession(current.sessionId);
+  c.sdk = null;
+  c.lastScreenshotBase64 = null;
+  c.elementRefs.clear();
+  c.sdkGeneration++;
 }
 
 // =============================================================================
@@ -281,12 +342,71 @@ function bareBase64(s: string): string {
  */
 function realtimeIsHealthy(s: any): boolean {
   try {
-    return s?.sandbox?._ably?.connection?.state === "connected";
+    return sdkIsConnected(s) && s?.sandbox?._ably?.connection?.state === "connected";
   } catch {
     return false;
   }
 }
 
+/**
+ * Whether `s` is an SDK that has finished connecting.
+ *
+ * `connected` flips to true only at the end of `connect()` and is exactly what
+ * the SDK's own `_ensureConnected()` guards every command on, so it is the one
+ * honest answer to "can I use this handle". Checking only for the *object* let a
+ * still-connecting SDK pass as usable. Optional-chained and defensive: an
+ * unusable handle must read as not-connected rather than throw.
+ */
+function sdkIsConnected(s: any): boolean {
+  try {
+    return s?.connected === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Close a sandbox we built but are not going to publish (we lost the epoch race).
+ * Best-effort, but worth awaiting: `close()` publishes `end-session` and leaves
+ * presence, which releases the team concurrency slot immediately instead of
+ * letting the orphan pin it for the full keepAlive window.
+ */
+async function discardSdk(sdk: any): Promise<void> {
+  try {
+    await sdk?.sandbox?.close?.();
+  } catch {
+    /* best effort — the server reaps the orphan on lease expiry regardless */
+  }
+}
+
+/**
+ * Publish `sdk` as the context's handle, unless a newer flow superseded us while
+ * we were connecting. Returns false when superseded, having closed the sandbox we
+ * built so it can't linger as an orphan holding a concurrency slot.
+ *
+ * Call this immediately after `connect()` resolves and before touching `c.sdk`.
+ */
+async function publishSdk(c: CoreContext, sdk: any, generation: number): Promise<boolean> {
+  if (c.sdkGeneration !== generation) {
+    await discardSdk(sdk);
+    return false;
+  }
+  c.sdk = sdk;
+  return true;
+}
+
+/** Result for a `sessionStart` that lost the epoch race to a newer session_start. */
+function supersededResult(): ActionResult {
+  return {
+    ok: false,
+    text:
+      "This session_start was superseded by a newer one that is already connected. " +
+      "The sandbox this call provisioned has been released. Use the active session, " +
+      "or call session_end and then session_start if you need a fresh sandbox.",
+    data: { action: "session_start", error: "SESSION_SUPERSEDED" },
+  };
+}
+
 /**
  * Attempt to rebuild the singleton from the adapter-registered recovery hook.
  * Returns true if a usable session now exists, false if there was nothing to
@@ -390,10 +510,17 @@ async function requireActiveSession(): Promise<void> {
   c.sessions.refreshSession(current.sessionId);
 }
 
-/** Capture a fresh full-screen screenshot as bare base64 (or null on failure). */
-async function captureScreen(): Promise<string | null> {
+/**
+ * Capture a fresh full-screen screenshot as bare base64 (or null on failure).
+ *
+ * Pass an explicit `sdk` from any flow that owns a local handle (`sessionStart`):
+ * reading `ctx().sdk` there would let a concurrent rebuild swap the instance out
+ * between provisioning and the screenshot. Actions that have already been through
+ * `requireActiveSession()` can omit it — the context's SDK is the right one.
+ */
+async function captureScreen(sdk: any = ctx().sdk): Promise<string | null> {
   try {
-    const b64 = await ctx().sdk.agent.system.captureScreenBase64(1, false, true);
+    const b64 = await sdk.agent.system.captureScreenBase64(1, false, true);
     return b64 || null;
   } catch {
     return null;
@@ -432,12 +559,13 @@ export async function sessionStart(
     }
   }
 
-  const newSession = c.sessions.createSession({
-    os: resolved.os,
-    keepAlive: params.keepAlive,
-    testFile: params.testFile,
-  });
-
+  // NOTE: the session is deliberately NOT created here. `createSession()` marks
+  // the new session *current* immediately, with status "initializing" — and
+  // `isSessionValid()` accepts that status — so creating it before `connect()`
+  // published a half-real session to every concurrent reader, and a `connect()`
+  // that threw or stalled (e.g. polling for a free concurrency slot) left it
+  // current forever. That is the `session_status: initializing` that never
+  // resolves. We create and activate it below, only once we have a live sandbox.
   const apiRoot = params.apiRoot || process.env.TD_API_ROOT || "https://api.testdriver.ai";
   const previewMode = process.env.TD_PREVIEW || "ide";
   const instanceIp = params.ip || process.env.TD_IP;
@@ -459,8 +587,16 @@ export async function sessionStart(
     };
   }
 
+  // Build into a LOCAL handle and publish to `c.sdk` only once `connect()` has
+  // resolved. Assigning `c.sdk` up front exposed an SDK whose `connected` flag is
+  // still false to every concurrent reader, and — because each step below used to
+  // re-read `c.sdk` — let a concurrent rebuild swap the instance out *between*
+  // connect and provision, so provisioning ran against a handle that had never
+  // been connected and threw "SDK is not connected. Call connect() first."
+  // Everything below uses `sdk`; `c.sdk` is written exactly once, at publish.
+  const generation = ++c.sdkGeneration;
   const TestDriverSDK = (await loadTestDriverSdk()).default;
-  c.sdk = new TestDriverSDK(apiKey, {
+  const sdk = new TestDriverSDK(apiKey, {
     os: resolved.os,
     logging: false,
     apiRoot,
@@ -472,12 +608,19 @@ export async function sessionStart(
   // Debug mode — attach to an existing sandbox, skip provisioning.
   if (params.sandboxId) {
     progress(`Connecting to existing sandbox ${params.sandboxId}...`);
-    await c.sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
-    const instance = c.sdk.getInstance();
+    await sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
+    if (!(await publishSdk(c, sdk, generation))) return supersededResult();
+
+    const instance = sdk.getInstance();
+    const newSession = c.sessions.createSession({
+      os: resolved.os,
+      keepAlive: params.keepAlive,
+      testFile: params.testFile,
+    });
     c.sessions.activateSession(newSession.sessionId, instance?.instanceId || params.sandboxId);
 
     progress("Capturing screenshot...");
-    const shot = await captureScreen();
+    const shot = await captureScreen(sdk);
     if (shot) c.lastScreenshotBase64 = shot;
 
     return {
@@ -490,9 +633,15 @@ export async function sessionStart(
   }
 
   progress(instanceIp ? `Connecting to self-hosted instance ${instanceIp}...` : "Connecting to cloud sandbox...");
-  await c.sdk.connect({ reconnect: params.reconnect, keepAlive: params.keepAlive, ip: instanceIp });
+  await sdk.connect({ reconnect: params.reconnect, keepAlive: params.keepAlive, ip: instanceIp });
+  if (!(await publishSdk(c, sdk, generation))) return supersededResult();
 
-  const instance = c.sdk.getInstance();
+  const instance = sdk.getInstance();
+  const newSession = c.sessions.createSession({
+    os: resolved.os,
+    keepAlive: params.keepAlive,
+    testFile: params.testFile,
+  });
   c.sessions.activateSession(newSession.sessionId, instance?.instanceId || "unknown");
 
   const provisionOptions = getProvisionOptions(params);
@@ -501,29 +650,29 @@ export async function sessionStart(
   progress(`Provisioning ${params.type}...`);
   switch (params.type) {
     case "chrome":
-      await c.sdk.provision.chrome(provisionOptions);
+      await sdk.provision.chrome(provisionOptions);
       provisionCmd = "provision.chrome";
       break;
     case "chromeExtension":
-      await c.sdk.provision.chromeExtension(provisionOptions);
+      await sdk.provision.chromeExtension(provisionOptions);
       provisionCmd = "provision.chromeExtension";
       break;
     case "vscode":
-      await c.sdk.provision.vscode(provisionOptions);
+      await sdk.provision.vscode(provisionOptions);
       provisionCmd = "provision.vscode";
       break;
     case "installer":
-      await c.sdk.provision.installer(provisionOptions);
+      await sdk.provision.installer(provisionOptions);
       provisionCmd = "provision.installer";
       break;
     case "electron":
-      await c.sdk.provision.electron(provisionOptions);
+      await sdk.provision.electron(provisionOptions);
       provisionCmd = "provision.electron";
       break;
   }
 
   progress("Capturing screenshot...");
-  const shot = await captureScreen();
+  const shot = await captureScreen(sdk);
   if (shot) c.lastScreenshotBase64 = shot;
 
   const debuggerUrl = instance?.debuggerUrl || (instanceIp ? `http://${instanceIp}:9222` : null);
@@ -590,14 +739,14 @@ export async function reconnectSession(params: ReconnectParams): Promise<string>
   const apiRoot = params.apiRoot || process.env.TD_API_ROOT || "https://api.testdriver.ai";
   const previewMode = process.env.TD_PREVIEW || "ide";
 
-  const session = c.sessions.createSession({
-    os: params.os,
-    keepAlive: params.keepAlive,
-    testFile: params.testFile,
-  });
-
+  // Local handle + epoch, published only after connect() — see sessionStart and
+  // CoreContext.sdkGeneration. This path is the one an abandoned action reaches
+  // (eve stops waiting on a slow action but cannot cancel it, so the zombie keeps
+  // running and calls in here), which is exactly how a stale rebuild used to land
+  // on top of a newer, healthy SDK.
+  const generation = ++c.sdkGeneration;
   const TestDriverSDK = (await loadTestDriverSdk()).default;
-  c.sdk = new TestDriverSDK(params.apiKey, {
+  const sdk = new TestDriverSDK(params.apiKey, {
     os: params.os,
     logging: false,
     apiRoot,
@@ -606,8 +755,27 @@ export async function reconnectSession(params: ReconnectParams): Promise<string>
     e2bTemplateId: params.e2bTemplateId,
   });
 
-  await c.sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
-  const instance = c.sdk.getInstance();
+  await sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
+
+  // Superseded: a newer rebuild already published a live SDK. Release the sandbox
+  // we just attached (`publishSdk` closes it) and hand back the winner's session
+  // rather than clobbering it. The session is only created on the winning path, so
+  // a loser never leaves a stray "initializing" session current.
+  if (!(await publishSdk(c, sdk, generation))) {
+    const current = c.sessions.getCurrentSession();
+    if (current && c.sessions.isSessionValid(current.sessionId)) return current.sessionId;
+    throw new NoActiveSessionError(
+      "SESSION_EXPIRED",
+      "The sandbox connection was superseded and no active session remains. Call session_start again to create a new sandbox session."
+    );
+  }
+
+  const session = c.sessions.createSession({
+    os: params.os,
+    keepAlive: params.keepAlive,
+    testFile: params.testFile,
+  });
+  const instance = sdk.getInstance();
   c.sessions.activateSession(session.sessionId, instance?.instanceId || params.sandboxId);
   return session.sessionId;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testdriverai/mcp",
-  "version": "7.11.10-canary",
+  "version": "7.11.11-canary",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",