@testdriverai/agent 7.11.100-test → 7.11.101-test

package/ai/skills/testdriver-ci-cd/SKILL.md

@@ -14,7 +14,7 @@ workflow is running inside your org and TestDriver exchanges that proof for your
 team's key at run time. See the GitHub Actions tab below.
 
 For other CI providers (or self-hosted runners without OIDC), fall back to a
-stored API key from [console.testdriver.ai/team](https://console.testdriver.ai/team),
+stored API key from [console.testdriver.ai/settings](https://console.testdriver.ai/settings),
 added as a `TD_API_KEY` secret in your CI provider's settings.
 
 <Note>

package/ai/skills/testdriver-client/SKILL.md

@@ -17,7 +17,7 @@ const testdriver = new TestDriver(apiKey, options)
 ### Parameters
 
 <ParamField path="apiKey" type="string" required>
-  Your TestDriver API key from the [dashboard](https://console.testdriver.ai/team)
+  Your TestDriver API key from the [dashboard](https://console.testdriver.ai/settings)
 </ParamField>
 
 <ParamField path="options" type="object">

package/ai/skills/testdriver-quickstart/SKILL.md

@@ -116,7 +116,7 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
     `init` detects clients already present in your project and pre-selects them in the picker. Re-running `init` is safe — it merges the TestDriver entry into existing config without overwriting your other servers.
     </Info>
 
-    You'll need a TestDriver API key. Create one at [console.testdriver.ai/team](https://console.testdriver.ai/team) and `init` will save it to `.env` as `TD_API_KEY`.
+    You'll need a TestDriver API key. Create one at [console.testdriver.ai/settings](https://console.testdriver.ai/settings) and `init` will save it to `.env` as `TD_API_KEY`.
 
     ### The agent
 
@@ -261,7 +261,7 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
             {
               "type": "promptString",
               "id": "testdriver-api-key",
-              "description": "TestDriver API Key From https://console.testdriver.ai/team",
+              "description": "TestDriver API Key From https://console.testdriver.ai/settings",
               "password": true
             }
           ]
@@ -357,7 +357,7 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
         <Card
           title="Get an API Key"
           icon="user-plus"
-          href="https://console.testdriver.ai/team"
+          href="https://console.testdriver.ai/settings"
           arrow
           horizontal
         >

package/debugger/index.html

@@ -458,18 +458,20 @@
         };
       }
 
-      // Responsive: scale and center the overlay to fit the window
+      // Responsive: scale and center the overlay to fit the window. No 1x cap —
+      // the embedder sizes the iframe to the sandbox's aspect ratio, so the
+      // overlay should scale up to fill it rather than sit letterboxed at 1x.
       const resizeOverlay = () => {
         const ww = window.innerWidth;
         const wh = window.innerHeight;
-        const scale = Math.min(ww / overlayWidth, wh / overlayHeight, 1);
+        const scale = Math.min(ww / overlayWidth, wh / overlayHeight);
         const sw = overlayWidth * scale;
         const sh = overlayHeight * scale;
 
         overlay.style.width = overlayWidth + "px";
         overlay.style.height = overlayHeight + "px";
         overlay.style.position = "absolute";
-        overlay.style.transform = scale < 1 ? `scale(${scale})` : "none";
+        overlay.style.transform = `scale(${scale})`;
         overlay.style.left = `${(ww - sw) / 2}px`;
         overlay.style.top = `${(wh - sh) / 2}px`;
       };

package/docs/docs.json

@@ -17,9 +17,45 @@
         "version": "v7",
         "groups": [
           {
-            "group": "Overview",
+            "group": "Quick Start",
             "pages": [
+              "/v7/what-is-testdriver",
+              "/v7/hosted",
+              "/v7/agent",
               "/v7/quickstart",
+              "/changelog"
+            ]
+          },
+          {
+            "group": "Tutorial",
+            "pages": [
+              "/v7/provision",
+              "/v7/screenshots",
+              "/v7/elements",
+              "/v7/performing-actions",
+              "/v7/making-assertions",
+              "/v7/generating-tests"
+            ]
+          },
+          {
+            "group": "Guides",
+            "pages": [
+              "/v7/copilot/running-tests",
+              "/v7/variables",
+              "/v7/secrets",
+              "/v7/reusable-code",
+              {
+                "group": "Self-host TestDriver",
+                "icon": "server",
+                "pages": [
+                  "/v7/self-hosted",
+                  "/v7/aws-setup"
+                ]
+              },
+              "/v7/ci-cd",
+              "/v7/caching",
+              "/v7/debugging-with-screenshots",
+              "/v7/copilot/auto-healing",
               {
                 "group": "Examples",
                 "icon": "code",
@@ -38,77 +74,50 @@
                   "/v7/examples/scroll",
                   "/v7/examples/type"
                 ]
-              },
-              "/v7/what-is-testdriver",
-              "/v7/agent",
-              {
-                "group": "Deployment",
-                "icon": "server",
-                "pages": [
-                  "/v7/hosted",
-                  "/v7/self-hosted"
-                ]
-              },
-              "/changelog"
-            ]
-          },
-          {
-            "group": "Guide",
-            "pages": [
-              "/v7/generating-tests",
-              "/v7/caching",
-              "/v7/copilot/running-tests",
-              "/v7/making-assertions",
-              "/v7/performing-actions",
-              "/v7/debugging-with-screenshots",
-              "/v7/copilot/auto-healing",
-              "/v7/ci-cd",
-              "/v7/test-results-json"
+              }
             ]
           },
           {
-            "group": "Scaling",
+            "group": "Reference",
             "pages": [
-              "/v7/variables",
-              "/v7/secrets",
-              "/v7/reusable-code",
               {
-                "group": "Self-Hosting",
-                "icon": "server",
+                "group": "Commands",
+                "icon": "terminal",
                 "pages": [
-                  "/v7/aws-setup"
+                  "/v7/assert",
+                  "/v7/captcha",
+                  "/v7/click",
+                  "/v7/double-click",
+                  "/v7/exec",
+                  "/v7/extract",
+                  "/v7/find",
+                  "/v7/focus-application",
+                  "/v7/hover",
+                  "/v7/mouse-down",
+                  "/v7/mouse-up",
+                  "/v7/parse",
+                  "/v7/press-keys",
+                  "/v7/right-click",
+                  "/v7/screenshot",
+                  "/v7/scroll",
+                  "/v7/type",
+                  "/v7/wait"
                 ]
-              }
-            ]
-          },
-          {
-            "group": "Actions",
-            "pages": [
-              "/v7/assert",
-              "/v7/captcha",
-              "/v7/click",
-              "/v7/double-click",
-              "/v7/exec",
-              "/v7/extract",
-              "/v7/find",
-              "/v7/focus-application",
-              "/v7/hover",
-              "/v7/mouse-down",
-              "/v7/mouse-up",
-              "/v7/parse",
-              "/v7/press-keys",
-              "/v7/right-click",
-              "/v7/screenshot",
-              "/v7/scroll",
-              "/v7/type"
-            ]
-          },
-          {
-            "group": "SDK Reference",
-            "pages": [
-              "/v7/client",
-              "/v7/elements",
-              "/v7/dashcam"
+              },
+              {
+                "group": "Configuration",
+                "icon": "sliders",
+                "pages": [
+                  "/v7/customizing-devices",
+                  "/v7/client",
+                  "/v7/cache",
+                  "/v7/redraw",
+                  "/v7/dashcam",
+                  "/v7/events",
+                  "/v7/errors"
+                ]
+              },
+              "/v7/test-results-json"
             ]
           }
         ]

package/docs/v7/agent.mdx

@@ -1,6 +1,6 @@
 ---
 title: "The TestDriver Agent"
-sidebarTitle: "Agent"
+sidebarTitle: "GitHub App"
 description: "How the TestDriver agent behaves on GitHub issues, pull requests, and @mentions"
 icon: "robot"
 ---

package/docs/v7/aws-setup.mdx

@@ -1,6 +1,6 @@
 ---
 title: "AWS Setup Guide"
-sidebarTitle: "AWS Setup Guide"
+sidebarTitle: "AWS setup"
 description: "Deploy TestDriver on your AWS infrastructure using CloudFormation"
 icon: "aws"
 ---

package/docs/v7/caching.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Learn"
-sidebarTitle: "Learn"
+sidebarTitle: "Cache test runs"
 description: "How TestDriver learns your app and caches what it discovers for instant, deterministic replays"
 icon: "brain"
 ---

package/docs/v7/ci-cd.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Integrating into CI/CD"
-sidebarTitle: "Integrating into CI/CD"
+sidebarTitle: "Run tests in CI"
 description: "Run TestDriver tests in CI/CD with parallel execution and cross-platform support"
 icon: "code-branch"
 ---

package/docs/v7/copilot/auto-healing.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Prevent"
-sidebarTitle: "Prevent"
+sidebarTitle: "Auto-heal tests"
 description: "Catch regressions automatically with CI, auto-healing, and GitHub integration"
 icon: "shield-check"
 ---

package/docs/v7/copilot/running-tests.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Run"
-sidebarTitle: "Run"
+sidebarTitle: "Run tests locally"
 description: "Set up your environment and run TestDriver tests locally and in CI"
 icon: "play"
 ---

package/docs/v7/customizing-devices.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Customizing Devices"
+sidebarTitle: "Options"
 description: "Configure TestDriver sandbox options and environment settings"
 icon: "computer"
 ---

package/docs/v7/debugging-with-screenshots.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Debug"
-sidebarTitle: "Debug"
+sidebarTitle: "Debug failing tests"
 description: "Diagnose failing tests with screenshots, replays, and logs"
 icon: "bug"
 ---

package/docs/v7/elements.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Element Finding"
-sidebarTitle: "Elements"
+sidebarTitle: "Find elements"
 description: "Locate and interact with UI elements using AI"
 icon: "mouse-pointer"
 ---

package/docs/v7/generating-tests.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Explore"
-sidebarTitle: "Explore"
+sidebarTitle: "Put it together"
 description: "Generate tests by exploring your app with the AI vision agent"
 icon: "compass"
 ---

package/docs/v7/hosted.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Hosted"
-sidebarTitle: "Hosted"
+sidebarTitle: "TestDriver Console"
 description: "The fastest way to get started with TestDriver. Just set your API key and start testing."
 icon: "cloud"
 mode: "wide"

package/docs/v7/performing-actions.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Adapt"
-sidebarTitle: "Adapt"
+sidebarTitle: "Interact"
 description: "Perform actions and handle dynamic, async UI so tests adapt to change"
 icon: "arrows-rotate"
 ---

package/docs/v7/provision.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Provision"
-sidebarTitle: "Provision"
+sidebarTitle: "Set up a sandbox"
 description: "Launch browsers, desktop apps, and extensions in your sandbox"
 icon: "rocket"
 mode: "wide"

package/docs/v7/quickstart.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Quick Start"
-sidebarTitle: "Quickstart"
+sidebarTitle: "CLI"
 description: "Run your first computer-use test in minutes."
 icon: "rocket"
 ---

package/docs/v7/reusable-code.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Reusable Code Snippets"
+sidebarTitle: "Use code snippets"
 description: "Build maintainable test suites with reusable code patterns"
 icon: "recycle"
 ---

package/docs/v7/screenshots.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Screenshots"
-sidebarTitle: "Screenshots"
+sidebarTitle: "Look at the screen"
 description: "Capture and manage screenshots during test execution"
 icon: "camera"
 mode: "wide"

package/docs/v7/secrets.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Using Secrets"
+sidebarTitle: "Use secrets"
 description: "Securely manage passwords and sensitive data in your tests"
 icon: "key"
 ---

package/docs/v7/self-hosted.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Self-Hosted (Enterprise)"
-sidebarTitle: "Self-Hosted"
+sidebarTitle: "Overview"
 description: "Our enterprise solution with unlimited test execution, assisted setup, and dedicated support."
 icon: "server"
 mode: "wide"

package/docs/v7/test-results-json.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Test Result JSON"
-sidebarTitle: "Test Result JSON"
+sidebarTitle: "Test format"
 description: "Per-test JSON result files with metadata, versions, and infrastructure details"
 icon: "file-code"
 ---

package/docs/v7/variables.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Using Variables"
+sidebarTitle: "Use variables"
 description: "Use dynamic data and secure secrets in your tests"
 icon: "square-root-variable"
 ---

package/docs/v7/what-is-testdriver.mdx

@@ -1,5 +1,6 @@
 ---
 title: "What is TestDriver?"
+sidebarTitle: "What is TestDriver?"
 description: "Reliably test your most difficult user flows"
 icon: "circle-info"
 ---

package/interfaces/vitest-plugin.mjs

@@ -295,6 +295,7 @@ export const pluginState = {
   detectedPlatform: null,
   pendingTestCaseRecords: new Set(),
   ciProvider: null,
+  isCI: false,
   gitInfo: {},
   apiKey: null,
   apiRoot: null,
@@ -773,6 +774,7 @@ export default function testDriverPlugin(options = {}) {
     process.env.TD_API_ROOT ||
     channelConfig.channels[channelConfig.active];
   pluginState.ciProvider = detectCI();
+  pluginState.isCI = detectIsCI();
   pluginState.gitInfo = getGitInfo();
 
   // Store TestDriver-specific options (excluding plugin-specific ones)
@@ -788,6 +790,7 @@ export default function testDriverPlugin(options = {}) {
   logger.debug("API key from options:", !!options.apiKey);
   logger.debug("API key from env (at config time):", !!process.env.TD_API_KEY);
   logger.debug("CI Provider:", pluginState.ciProvider || "none");
+  logger.debug("Is CI:", pluginState.isCI);
   if (Object.keys(testDriverOptions).length > 0) {
     logger.debug("Global TestDriver options:", testDriverOptions);
   }
@@ -882,6 +885,7 @@ class TestDriverReporter {
       if (pluginState.ciProvider) {
         testRunData.ciProvider = pluginState.ciProvider;
       }
+      testRunData.isCI = pluginState.isCI;
 
       // Platform will be set from the first test result file
       // Default to linux if no tests write platform info
@@ -1471,6 +1475,17 @@ function detectCI() {
   return null;
 }
 
+// Broader than detectCI(): virtually every CI provider exports CI=true, so this
+// still reports true on providers we don't name (Azure, TeamCity, Woodpecker,
+// self-hosted runners...). Vitest and other tools also set CI=true themselves
+// when they detect one, so this is the value we trust for "was this run in CI".
+function detectIsCI() {
+  if (detectCI()) return true;
+  const ci = process.env.CI;
+  if (!ci) return false;
+  return ci !== "false" && ci !== "0";
+}
+
 function getGitInfo() {
   const info = {};
 

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

@@ -83,6 +83,18 @@ export interface CoreContext {
     sdkGeneration: number;
     lastScreenshotBase64: string | null;
     reconnectResolver: ReconnectResolver | null;
+    /** Notified once a sandbox is proven gone, so durable adapters drop their handle. */
+    onRecoveryFailed: RecoveryFailedHook | null;
+    /**
+     * Sandboxes this context has already failed to reconnect to.
+     *
+     * A dead sandbox never comes back, but nothing used to remember that: the
+     * durable handle still named it, so every following action re-entered recovery,
+     * and each attempt bumped {@link sdkGeneration} before failing. Those bumps are
+     * what turned one expiry into the SESSION_SUPERSEDED loop — a genuine
+     * `session_start` racing a queue of doomed rebuilds could never win the publish.
+     */
+    deadSandboxIds: Set<string>;
     /** In-flight reconnect, so concurrent actions in one context share one rebuild. */
     reconnecting: Promise<void> | null;
     /** Stored element instances from `find`/`findall`, addressable by ref. */
@@ -147,11 +159,20 @@ export declare function getSessionTimeRemaining(sessionId: string): number;
  * so a stale closure can't outlive the process it was bound to.
  */
 export type ReconnectResolver = () => Promise<ReconnectParams | null>;
+/**
+ * Called once mcp-core has proven a sandbox is unreachable, so the durable owner
+ * can drop its handle. Without it the two stores disagree: mcp-core knows the
+ * sandbox is dead while eve's durable slot still names it, so the resolver keeps
+ * handing back the same corpse and every action re-enters recovery.
+ */
+export type RecoveryFailedHook = (sandboxId: string) => void;
 /**
  * Register (or clear, with `null`) the recovery hook. Durable adapters call this
  * at the start of each step with a resolver bound to the current tool context.
  */
 export declare function setReconnectResolver(resolver: ReconnectResolver | null): void;
+/** Register (or clear) the callback fired when a sandbox is proven unreachable. */
+export declare function setRecoveryFailedHook(hook: RecoveryFailedHook | null): void;
 /** Expose internals the adapters legitimately need (read-only intent). */
 export declare function getSdk(): any;
 export declare function getLastScreenshotBase64(): string | null;
@@ -204,6 +225,14 @@ export declare function clearSession(): void;
 export interface SessionStartHooks {
     /** Called before a long await; return a stop fn. Lets adapters heartbeat. */
     onProgress?: (message: string) => void;
+    /**
+     * Fired once the sandbox is connected and published to the context, BEFORE
+     * provisioning starts. Provisioning is the slow part (~20s+), but the live
+     * VNC stream is already watchable at this point — this is the hook an adapter
+     * uses to surface the viewer URL early instead of at the end of the call.
+     * Runs inside the context, so `getSdk()`/`getInstance()` are valid here.
+     */
+    onSandboxLive?: () => void;
 }
 /**
  * Start a session and provision a sandbox. The adapter is responsible for

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

@@ -42,6 +42,8 @@ export function createCoreContext() {
         sdkGeneration: 0,
         lastScreenshotBase64: null,
         reconnectResolver: null,
+        onRecoveryFailed: null,
+        deadSandboxIds: new Set(),
         reconnecting: null,
         elementRefs: new Map(),
         // Reuse the shared SessionManager for the global context so that consumers
@@ -100,6 +102,10 @@ export function getSessionTimeRemaining(sessionId) {
 export function setReconnectResolver(resolver) {
     ctx().reconnectResolver = resolver;
 }
+/** Register (or clear) the callback fired when a sandbox is proven unreachable. */
+export function setRecoveryFailedHook(hook) {
+    ctx().onRecoveryFailed = hook;
+}
 /** Expose internals the adapters legitimately need (read-only intent). */
 export function getSdk() {
     return ctx().sdk;
@@ -269,14 +275,27 @@ async function publishSdk(c, sdk, generation) {
     c.sdk = sdk;
     return true;
 }
-/** Result for a `sessionStart` that lost the epoch race to a newer session_start. */
-function supersededResult() {
+/**
+ * Result for a `sessionStart` that lost the epoch race to a newer flow.
+ *
+ * The advice has to depend on what actually survived. A supersede does NOT imply
+ * a healthy winner: the flow that bumped the epoch past us may itself have failed
+ * (the common case is a recovery rebuild of an already-dead sandbox). Telling the
+ * agent to "use the active session" when there is none sent it into the
+ * session_status → session_end → session_start loop this guard exists to prevent.
+ */
+function supersededResult(c) {
+    const current = c.sessions.getCurrentSession();
+    const live = sdkIsConnected(c.sdk) && !!current && c.sessions.isSessionValid(current.sessionId);
     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" },
+        text: live
+            ? "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."
+            : "This session_start raced a concurrent reconnect and neither connection survived. " +
+                "No sandbox is held now and no cleanup is needed — call session_start once more.",
+        data: { action: "session_start", error: "SESSION_SUPERSEDED", hasActiveSession: live },
     };
 }
 /**
@@ -298,6 +317,12 @@ async function tryRecoverSession() {
             const params = await resolver();
             if (!params?.sandboxId)
                 return; // nothing provisioned this session
+            // Already proven gone — don't rebuild toward a corpse. Recovering costs an
+            // epoch bump, and repeating it is what starves a concurrent session_start
+            // of its publish. Report it as NO_SESSION so the caller re-provisions.
+            if (c.deadSandboxIds.has(params.sandboxId)) {
+                throw new NoActiveSessionError("NO_SESSION", "The previous sandbox is gone and no new one has been started. Call session_start to create one.");
+            }
             // Close any half-dead socket on the outgoing SDK before replacing it, so a
             // parked-then-rebuilt session doesn't leak an orphaned Ably connection.
             try {
@@ -306,7 +331,13 @@ async function tryRecoverSession() {
             catch {
                 /* best effort — reconnectSession installs a fresh SDK regardless */
             }
-            await reconnectSession(params);
+            try {
+                await reconnectSession(params);
+            }
+            catch (err) {
+                markSandboxDead(c, params.sandboxId);
+                throw err;
+            }
         })().finally(() => {
             c.reconnecting = null;
         });
@@ -323,6 +354,22 @@ async function tryRecoverSession() {
     const session = c.sessions.getCurrentSession();
     return !!c.sdk && !!session && c.sessions.isSessionValid(session.sessionId);
 }
+/**
+ * Record that `sandboxId` is unreachable and tell the durable owner to forget it.
+ *
+ * Both halves matter. The local set stops *this* process from retrying a rebuild
+ * it already knows will fail; the hook stops the durable store from handing the
+ * same id back after a recycle, which would defeat the set.
+ */
+function markSandboxDead(c, sandboxId) {
+    c.deadSandboxIds.add(sandboxId);
+    try {
+        c.onRecoveryFailed?.(sandboxId);
+    }
+    catch {
+        /* best effort — the local set alone still breaks the retry loop */
+    }
+}
 /**
  * Validate the active session and auto-extend it (active use keeps it alive),
  * mirroring the MCP server's `requireActiveSession`. When the in-process
@@ -393,6 +440,15 @@ async function captureScreen(sdk = ctx().sdk) {
 export async function sessionStart(params, resolved, hooks = {}) {
     const c = ctx();
     const progress = hooks.onProgress ?? (() => { });
+    // Best-effort: an adapter's notification must never fail the provision.
+    const sandboxLive = () => {
+        try {
+            hooks.onSandboxLive?.();
+        }
+        catch {
+            /* ignore */
+        }
+    };
     // Validate required fields for specific provision types (unless reconnecting).
     if (!params.sandboxId) {
         if (params.type === "installer" && !params.installerUrl) {
@@ -457,7 +513,8 @@ export async function sessionStart(params, resolved, hooks = {}) {
             requireSandbox: true,
         });
         if (!(await publishSdk(c, sdk, generation)))
-            return supersededResult();
+            return supersededResult(c);
+        sandboxLive();
         const instance = sdk.getInstance();
         const newSession = c.sessions.createSession({
             os: resolved.os,
@@ -480,7 +537,8 @@ export async function sessionStart(params, resolved, hooks = {}) {
     progress(instanceIp ? `Connecting to self-hosted instance ${instanceIp}...` : "Connecting to cloud sandbox...");
     await sdk.connect({ reconnect: params.reconnect, keepAlive: params.keepAlive, ip: instanceIp });
     if (!(await publishSdk(c, sdk, generation)))
-        return supersededResult();
+        return supersededResult(c);
+    sandboxLive();
     const instance = sdk.getInstance();
     const newSession = c.sessions.createSession({
         os: resolved.os,
@@ -589,9 +647,13 @@ export async function reconnectSession(params) {
     // 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))
+        // Require a *connected* winner, not merely a current session: the flow that
+        // took the epoch may still be mid-`connect()`, and returning its id here told
+        // the caller a session was ready that no action could then use.
+        if (sdkIsConnected(c.sdk) && 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.");
+        }
+        throw new NoActiveSessionError("NO_SESSION", "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,
@@ -627,6 +689,11 @@ export async function ensureActiveSession(params) {
     if (!params?.sandboxId) {
         return false;
     }
+    // Proven gone already — skip the doomed rebuild (and the epoch bump it costs).
+    if (c.deadSandboxIds.has(params.sandboxId)) {
+        c.sdk = null;
+        throw new NoActiveSessionError("NO_SESSION", "The previous sandbox is gone and no new one has been started. Call session_start to create one.", params.sandboxId);
+    }
     try {
         await reconnectSession(params);
         return true;
@@ -636,6 +703,7 @@ export async function ensureActiveSession(params) {
         // id is stale). Surface a SESSION_EXPIRED so the adapter's mapper tells the
         // agent to call session_start again, instead of a raw connect error.
         c.sdk = null;
+        markSandboxDead(c, params.sandboxId);
         throw new NoActiveSessionError("SESSION_EXPIRED", `Could not reconnect to sandbox ${params.sandboxId}: ${err instanceof Error ? err.message : String(err)}. The sandbox has expired — call session_start again to create a new one.`, params.sandboxId);
     }
 }

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

@@ -12,8 +12,18 @@
  * could not serve a single command.
  */
 
-import { describe, it, expect } from "vitest";
-import { clearSession, createIsolatedContext, hasLiveSession, runInContext, type CoreContext } from "./actions.js";
+import { describe, it, expect, vi } from "vitest";
+import {
+  clearSession,
+  createIsolatedContext,
+  ensureActiveSession,
+  hasLiveSession,
+  NoActiveSessionError,
+  runInContext,
+  setRecoveryFailedHook,
+  type CoreContext,
+  type ReconnectParams,
+} from "./actions.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -102,6 +112,56 @@ describe("clearSession", () => {
   });
 });
 
+describe("ensureActiveSession with a dead sandbox", () => {
+  /** Reconnect params naming a sandbox the server no longer has. */
+  const params = (): ReconnectParams => ({
+    sandboxId: "sb-dead",
+    os: "linux",
+    keepAlive: 60_000,
+    apiKey: "k",
+  });
+
+  it("does not bump the epoch again once the sandbox is known dead", async () => {
+    // The loop's engine: every retry against a corpse used to bump the epoch, so
+    // a real session_start racing them could never win its publish.
+    const c = createIsolatedContext();
+    c.deadSandboxIds.add("sb-dead");
+    const before = c.sdkGeneration;
+
+    await expect(
+      runInContext(c, () => ensureActiveSession(params())),
+    ).rejects.toBeInstanceOf(NoActiveSessionError);
+
+    expect(c.sdkGeneration).toBe(before);
+  });
+
+  it("reports NO_SESSION, not SESSION_EXPIRED, so the agent just re-provisions", async () => {
+    const c = createIsolatedContext();
+    c.deadSandboxIds.add("sb-dead");
+    await runInContext(c, () => ensureActiveSession(params())).catch((err) => {
+      expect(err).toBeInstanceOf(NoActiveSessionError);
+      expect((err as NoActiveSessionError).code).toBe("NO_SESSION");
+    });
+  });
+
+  it("tells the durable owner to forget a sandbox it just proved unreachable", async () => {
+    // Without this the durable store keeps handing back the dead id after a
+    // recycle wipes deadSandboxIds, and recovery loops again.
+    const c = createIsolatedContext();
+    const forgotten = vi.fn();
+
+    await runInContext(c, async () => {
+      setRecoveryFailedHook(forgotten);
+      // No SDK is loadable in unit tests, so reconnectSession throws — which is
+      // exactly the "sandbox is gone" path.
+      await ensureActiveSession(params()).catch(() => {});
+    });
+
+    expect(forgotten).toHaveBeenCalledWith("sb-dead");
+    expect(c.deadSandboxIds.has("sb-dead")).toBe(true);
+  });
+});
+
 describe("createIsolatedContext", () => {
   it("starts at generation 0 so the first build wins its epoch", () => {
     expect(createIsolatedContext().sdkGeneration).toBe(0);

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

@@ -106,6 +106,18 @@ export interface CoreContext {
   sdkGeneration: number;
   lastScreenshotBase64: string | null;
   reconnectResolver: ReconnectResolver | null;
+  /** Notified once a sandbox is proven gone, so durable adapters drop their handle. */
+  onRecoveryFailed: RecoveryFailedHook | null;
+  /**
+   * Sandboxes this context has already failed to reconnect to.
+   *
+   * A dead sandbox never comes back, but nothing used to remember that: the
+   * durable handle still named it, so every following action re-entered recovery,
+   * and each attempt bumped {@link sdkGeneration} before failing. Those bumps are
+   * what turned one expiry into the SESSION_SUPERSEDED loop — a genuine
+   * `session_start` racing a queue of doomed rebuilds could never win the publish.
+   */
+  deadSandboxIds: Set<string>;
   /** In-flight reconnect, so concurrent actions in one context share one rebuild. */
   reconnecting: Promise<void> | null;
   /** Stored element instances from `find`/`findall`, addressable by ref. */
@@ -131,6 +143,8 @@ export function createCoreContext(): CoreContext {
     sdkGeneration: 0,
     lastScreenshotBase64: null,
     reconnectResolver: null,
+    onRecoveryFailed: null,
+    deadSandboxIds: new Set(),
     reconnecting: null,
     elementRefs: new Map(),
     // Reuse the shared SessionManager for the global context so that consumers
@@ -213,6 +227,14 @@ export function getSessionTimeRemaining(sessionId: string): number {
  */
 export type ReconnectResolver = () => Promise<ReconnectParams | null>;
 
+/**
+ * Called once mcp-core has proven a sandbox is unreachable, so the durable owner
+ * can drop its handle. Without it the two stores disagree: mcp-core knows the
+ * sandbox is dead while eve's durable slot still names it, so the resolver keeps
+ * handing back the same corpse and every action re-enters recovery.
+ */
+export type RecoveryFailedHook = (sandboxId: string) => void;
+
 /**
  * Register (or clear, with `null`) the recovery hook. Durable adapters call this
  * at the start of each step with a resolver bound to the current tool context.
@@ -221,6 +243,11 @@ export function setReconnectResolver(resolver: ReconnectResolver | null): void {
   ctx().reconnectResolver = resolver;
 }
 
+/** Register (or clear) the callback fired when a sandbox is proven unreachable. */
+export function setRecoveryFailedHook(hook: RecoveryFailedHook | null): void {
+  ctx().onRecoveryFailed = hook;
+}
+
 /** Expose internals the adapters legitimately need (read-only intent). */
 export function getSdk(): any {
   return ctx().sdk;
@@ -395,15 +422,27 @@ async function publishSdk(c: CoreContext, sdk: any, generation: number): Promise
   return true;
 }
 
-/** Result for a `sessionStart` that lost the epoch race to a newer session_start. */
-function supersededResult(): ActionResult {
+/**
+ * Result for a `sessionStart` that lost the epoch race to a newer flow.
+ *
+ * The advice has to depend on what actually survived. A supersede does NOT imply
+ * a healthy winner: the flow that bumped the epoch past us may itself have failed
+ * (the common case is a recovery rebuild of an already-dead sandbox). Telling the
+ * agent to "use the active session" when there is none sent it into the
+ * session_status → session_end → session_start loop this guard exists to prevent.
+ */
+function supersededResult(c: CoreContext): ActionResult {
+  const current = c.sessions.getCurrentSession();
+  const live = sdkIsConnected(c.sdk) && !!current && c.sessions.isSessionValid(current.sessionId);
   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" },
+    text: live
+      ? "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."
+      : "This session_start raced a concurrent reconnect and neither connection survived. " +
+        "No sandbox is held now and no cleanup is needed — call session_start once more.",
+    data: { action: "session_start", error: "SESSION_SUPERSEDED", hasActiveSession: live },
   };
 }
 
@@ -424,6 +463,15 @@ async function tryRecoverSession(): Promise<boolean> {
     c.reconnecting = (async () => {
       const params = await resolver();
       if (!params?.sandboxId) return; // nothing provisioned this session
+      // Already proven gone — don't rebuild toward a corpse. Recovering costs an
+      // epoch bump, and repeating it is what starves a concurrent session_start
+      // of its publish. Report it as NO_SESSION so the caller re-provisions.
+      if (c.deadSandboxIds.has(params.sandboxId)) {
+        throw new NoActiveSessionError(
+          "NO_SESSION",
+          "The previous sandbox is gone and no new one has been started. Call session_start to create one."
+        );
+      }
       // Close any half-dead socket on the outgoing SDK before replacing it, so a
       // parked-then-rebuilt session doesn't leak an orphaned Ably connection.
       try {
@@ -431,7 +479,12 @@ async function tryRecoverSession(): Promise<boolean> {
       } catch {
         /* best effort — reconnectSession installs a fresh SDK regardless */
       }
-      await reconnectSession(params);
+      try {
+        await reconnectSession(params);
+      } catch (err) {
+        markSandboxDead(c, params.sandboxId);
+        throw err;
+      }
     })().finally(() => {
       c.reconnecting = null;
     });
@@ -450,6 +503,22 @@ async function tryRecoverSession(): Promise<boolean> {
   return !!c.sdk && !!session && c.sessions.isSessionValid(session.sessionId);
 }
 
+/**
+ * Record that `sandboxId` is unreachable and tell the durable owner to forget it.
+ *
+ * Both halves matter. The local set stops *this* process from retrying a rebuild
+ * it already knows will fail; the hook stops the durable store from handing the
+ * same id back after a recycle, which would defeat the set.
+ */
+function markSandboxDead(c: CoreContext, sandboxId: string): void {
+  c.deadSandboxIds.add(sandboxId);
+  try {
+    c.onRecoveryFailed?.(sandboxId);
+  } catch {
+    /* best effort — the local set alone still breaks the retry loop */
+  }
+}
+
 /**
  * Validate the active session and auto-extend it (active use keeps it alive),
  * mirroring the MCP server's `requireActiveSession`. When the in-process
@@ -534,6 +603,14 @@ async function captureScreen(sdk: any = ctx().sdk): Promise<string | null> {
 export interface SessionStartHooks {
   /** Called before a long await; return a stop fn. Lets adapters heartbeat. */
   onProgress?: (message: string) => void;
+  /**
+   * Fired once the sandbox is connected and published to the context, BEFORE
+   * provisioning starts. Provisioning is the slow part (~20s+), but the live
+   * VNC stream is already watchable at this point — this is the hook an adapter
+   * uses to surface the viewer URL early instead of at the end of the call.
+   * Runs inside the context, so `getSdk()`/`getInstance()` are valid here.
+   */
+  onSandboxLive?: () => void;
 }
 
 /**
@@ -548,6 +625,14 @@ export async function sessionStart(
 ): Promise<ActionResult> {
   const c = ctx();
   const progress = hooks.onProgress ?? (() => {});
+  // Best-effort: an adapter's notification must never fail the provision.
+  const sandboxLive = () => {
+    try {
+      hooks.onSandboxLive?.();
+    } catch {
+      /* ignore */
+    }
+  };
 
   // Validate required fields for specific provision types (unless reconnecting).
   if (!params.sandboxId) {
@@ -616,7 +701,8 @@ export async function sessionStart(
       keepAlive: params.keepAlive,
       requireSandbox: true,
     });
-    if (!(await publishSdk(c, sdk, generation))) return supersededResult();
+    if (!(await publishSdk(c, sdk, generation))) return supersededResult(c);
+    sandboxLive();
 
     const instance = sdk.getInstance();
     const newSession = c.sessions.createSession({
@@ -641,7 +727,8 @@ export async function sessionStart(
 
   progress(instanceIp ? `Connecting to self-hosted instance ${instanceIp}...` : "Connecting to cloud sandbox...");
   await sdk.connect({ reconnect: params.reconnect, keepAlive: params.keepAlive, ip: instanceIp });
-  if (!(await publishSdk(c, sdk, generation))) return supersededResult();
+  if (!(await publishSdk(c, sdk, generation))) return supersededResult(c);
+  sandboxLive();
 
   const instance = sdk.getInstance();
   const newSession = c.sessions.createSession({
@@ -781,9 +868,14 @@ export async function reconnectSession(params: ReconnectParams): Promise<string>
   // 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;
+    // Require a *connected* winner, not merely a current session: the flow that
+    // took the epoch may still be mid-`connect()`, and returning its id here told
+    // the caller a session was ready that no action could then use.
+    if (sdkIsConnected(c.sdk) && current && c.sessions.isSessionValid(current.sessionId)) {
+      return current.sessionId;
+    }
     throw new NoActiveSessionError(
-      "SESSION_EXPIRED",
+      "NO_SESSION",
       "The sandbox connection was superseded and no active session remains. Call session_start again to create a new sandbox session."
     );
   }
@@ -823,6 +915,15 @@ export async function ensureActiveSession(params?: ReconnectParams): Promise<boo
   if (!params?.sandboxId) {
     return false;
   }
+  // Proven gone already — skip the doomed rebuild (and the epoch bump it costs).
+  if (c.deadSandboxIds.has(params.sandboxId)) {
+    c.sdk = null;
+    throw new NoActiveSessionError(
+      "NO_SESSION",
+      "The previous sandbox is gone and no new one has been started. Call session_start to create one.",
+      params.sandboxId
+    );
+  }
   try {
     await reconnectSession(params);
     return true;
@@ -831,6 +932,7 @@ export async function ensureActiveSession(params?: ReconnectParams): Promise<boo
     // id is stale). Surface a SESSION_EXPIRED so the adapter's mapper tells the
     // agent to call session_start again, instead of a raw connect error.
     c.sdk = null;
+    markSandboxDead(c, params.sandboxId);
     throw new NoActiveSessionError(
       "SESSION_EXPIRED",
       `Could not reconnect to sandbox ${params.sandboxId}: ${err instanceof Error ? err.message : String(err)}. The sandbox has expired — call session_start again to create a new one.`,

package/mcp-server/src/core/session-isolation.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Regression cover for cross-session sandbox adoption.
+ *
+ * Observed in an `eve dev` log: session A provisioned `sb-725a91b9`, then a
+ * later, unrelated session B called `session_start` and got
+ * `warm_noop {sandboxId: "sb-725a91b9"}` — B adopted A's sandbox, drove A's
+ * browser, and then ended it. The cause was every eve session sharing mcp-core's
+ * ONE global context on a long-lived host.
+ *
+ * These tests pin the property eve now relies on: state keyed to a context is
+ * invisible to another context, and the epoch that drives SESSION_SUPERSEDED is
+ * per-context rather than shared.
+ */
+
+import { describe, it, expect } from "vitest";
+import { createIsolatedContext, hasLiveSession, runInContext, type CoreContext } from "./actions.js";
+
+/** A context that looks exactly like one holding a live, provisioned sandbox. */
+function contextWithLiveSandbox(sandboxId: string): CoreContext {
+  const c = createIsolatedContext();
+  c.sdk = { connected: true };
+  const session = c.sessions.createSession({ os: "linux", keepAlive: 60_000 });
+  c.sessions.activateSession(session.sessionId, sandboxId);
+  return c;
+}
+
+describe("per-session context isolation", () => {
+  it("does not show one session's live sandbox to another session", () => {
+    // The exact adoption bug: B must NOT see A's sandbox as its own warm session.
+    const a = contextWithLiveSandbox("sb-725a91b9");
+    const b = createIsolatedContext();
+
+    expect(runInContext(a, () => hasLiveSession())).toBe(true);
+    expect(runInContext(b, () => hasLiveSession())).toBe(false);
+  });
+
+  it("keeps each session's sandbox id to itself", () => {
+    const a = contextWithLiveSandbox("sb-aaa");
+    const b = contextWithLiveSandbox("sb-bbb");
+
+    const idIn = (c: CoreContext) =>
+      runInContext(c, () => c.sessions.getCurrentSession()?.sandboxId);
+
+    expect(idIn(a)).toBe("sb-aaa");
+    expect(idIn(b)).toBe("sb-bbb");
+  });
+
+  it("does not let one session's provision bump another's SDK epoch", () => {
+    // Shared epochs are why two concurrent sessions could each supersede the
+    // other's publish and neither could ever win — the SESSION_SUPERSEDED loop.
+    const a = createIsolatedContext();
+    const b = createIsolatedContext();
+    const bEpochBefore = b.sdkGeneration;
+
+    runInContext(a, () => {
+      a.sdkGeneration++;
+    });
+
+    expect(b.sdkGeneration).toBe(bEpochBefore);
+  });
+
+  it("does not leak element refs across sessions", () => {
+    const a = createIsolatedContext();
+    const b = createIsolatedContext();
+
+    a.elementRefs.set("el-1", {
+      element: {},
+      description: "login button",
+      coords: { x: 1, y: 2, centerX: 1, centerY: 2 },
+    });
+
+    expect(b.elementRefs.has("el-1")).toBe(false);
+  });
+});

package/package.json

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

package/sdk.js

@@ -3477,6 +3477,14 @@ CAPTCHA_SOLVER_EOF`,
       ciRunId: options.ci?.runId,
       ciJobId: options.ci?.jobId,
       ciUrl: options.ci?.url,
+      // Nearly every CI provider exports CI=true, including ones we have no
+      // named detection for, so this is the value to trust for "ran in CI".
+      isCI:
+        options.ci?.isCI ??
+        (!!options.ci?.provider ||
+          (!!process.env.CI &&
+            process.env.CI !== "false" &&
+            process.env.CI !== "0")),
       // Git
       repo: options.git?.repo,
       branch: options.git?.branch,