@testdriverai/agent 7.9.96-test → 7.9.97-canary

package/docs/_data/examples-manifest.json

@@ -2,18 +2,18 @@
   "$schema": "./examples-manifest.schema.json",
   "examples": {
     "assert.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a1640e572fbc49ea25d679b",
-      "replayUrl": "https://console-test.testdriver.ai/replay/6a164876cdb57a637d2faabd?share=P6veCnmKhjRh1lJK7aMx4g",
-      "embedUrl": "https://console-test.testdriver.ai/replay/6a164876cdb57a637d2faabd?share=P6veCnmKhjRh1lJK7aMx4g&embed=true",
-      "lastUpdated": "2026-05-27T01:27:24.420Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a17917a7d423e81b390fab1",
+      "replayUrl": "https://console-test.testdriver.ai/replay/6a1798e07d423e81b390fb43?share=UqiUSmkhK2HQemcBtpVI3w",
+      "embedUrl": "https://console-test.testdriver.ai/replay/6a1798e07d423e81b390fb43?share=UqiUSmkhK2HQemcBtpVI3w&embed=true",
+      "lastUpdated": "2026-05-28T01:22:47.847Z"
     },
     "drag-and-drop.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62b42fc0ac3cc632a918b",
       "lastUpdated": "2026-03-03T00:32:25.275Z"
     },
     "exec-pwsh.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16400472fbc49ea25d6715",
-      "lastUpdated": "2026-05-27T01:05:05.688Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a17908b7d423e81b390fa99",
+      "lastUpdated": "2026-05-28T01:01:50.685Z"
     },
     "match-image.test.mjs": {
       "url": "https://console-test.testdriver.ai/runs/69c8738614b73310c7839412/69c8738c14b73310c783941d",
@@ -24,92 +24,92 @@
       "lastUpdated": "2026-03-03T00:32:25.282Z"
     },
     "hover-text-with-description.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16401b72fbc49ea25d672e",
-      "lastUpdated": "2026-05-27T00:51:38.967Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1790a37d423e81b390fa9e",
+      "lastUpdated": "2026-05-28T00:47:30.860Z"
     },
     "windows-installer.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16404872fbc49ea25d6770",
-      "lastUpdated": "2026-05-27T01:06:16.047Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1790d37d423e81b390faa7",
+      "lastUpdated": "2026-05-28T01:03:02.727Z"
     },
     "exec-output.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16404a72fbc49ea25d6773",
-      "lastUpdated": "2026-05-27T01:06:17.437Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1790d57d423e81b390faa8",
+      "lastUpdated": "2026-05-28T01:03:04.886Z"
     },
     "chrome-extension.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16400272fbc49ea25d6713",
-      "lastUpdated": "2026-05-27T00:58:03.997Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1790897d423e81b390fa98",
+      "lastUpdated": "2026-05-28T00:54:24.116Z"
     },
     "launch-vscode-linux.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16403372fbc49ea25d6754",
-      "replayUrl": "https://console-test.testdriver.ai/replay/6a16461acdb57a637d2faaad?share=FN1SuaLYCODCJGkQQDUsQ",
-      "embedUrl": "https://console-test.testdriver.ai/replay/6a16461acdb57a637d2faaad?share=FN1SuaLYCODCJGkQQDUsQ&embed=true",
-      "lastUpdated": "2026-05-27T01:17:20.854Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1790c67d423e81b390faa5",
+      "replayUrl": "https://console-test.testdriver.ai/replay/6a1796cd7d423e81b390faed?share=vC6J7mIobNeQqdUdiZog",
+      "embedUrl": "https://console-test.testdriver.ai/replay/6a1796cd7d423e81b390faed?share=vC6J7mIobNeQqdUdiZog&embed=true",
+      "lastUpdated": "2026-05-28T01:13:57.213Z"
     },
     "hover-image.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16406072fbc49ea25d6784",
-      "lastUpdated": "2026-05-27T00:59:35.750Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1790ee7d423e81b390faab",
+      "lastUpdated": "2026-05-28T00:56:05.446Z"
     },
     "installer.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16408272fbc49ea25d6790",
-      "lastUpdated": "2026-05-27T00:53:10.678Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791107d423e81b390faac",
+      "lastUpdated": "2026-05-28T00:49:09.295Z"
     },
     "type.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a1640b772fbc49ea25d6799",
-      "lastUpdated": "2026-05-27T01:01:05.252Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791497d423e81b390faaf",
+      "lastUpdated": "2026-05-28T00:57:35.980Z"
     },
     "press-keys.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a1640cf72fbc49ea25d679a",
-      "replayUrl": "https://console-test.testdriver.ai/replay/6a164834cdb57a637d2faabb?share=shwxxjLJAs6ja39RQGXcTA",
-      "embedUrl": "https://console-test.testdriver.ai/replay/6a164834cdb57a637d2faabb?share=shwxxjLJAs6ja39RQGXcTA&embed=true",
-      "lastUpdated": "2026-05-27T01:26:18.025Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791627d423e81b390fab0",
+      "replayUrl": "https://console-test.testdriver.ai/replay/6a1798a77d423e81b390fb3c?share=HWIAWhrv9Umwbyi641bgg",
+      "embedUrl": "https://console-test.testdriver.ai/replay/6a1798a77d423e81b390fb3c?share=HWIAWhrv9Umwbyi641bgg&embed=true",
+      "lastUpdated": "2026-05-28T01:21:51.018Z"
     },
     "scroll-keyboard.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16411072fbc49ea25d679d",
-      "lastUpdated": "2026-05-27T01:09:42.258Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791aa7d423e81b390fab3",
+      "lastUpdated": "2026-05-28T01:06:34.229Z"
     },
     "scroll.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16412b72fbc49ea25d67a1",
-      "replayUrl": "https://console-test.testdriver.ai/replay/6a1649b84a4688499f88ea5d?share=gCsly4DGt4iQxlIjhHiceg",
-      "embedUrl": "https://console-test.testdriver.ai/replay/6a1649b84a4688499f88ea5d?share=gCsly4DGt4iQxlIjhHiceg&embed=true",
-      "lastUpdated": "2026-05-27T01:32:46.425Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791c77d423e81b390fab7",
+      "replayUrl": "https://console-test.testdriver.ai/replay/6a179a1b7d423e81b390fb6c?share=LaHVFvjLtWSJbRzmb9pQ",
+      "embedUrl": "https://console-test.testdriver.ai/replay/6a179a1b7d423e81b390fb6c?share=LaHVFvjLtWSJbRzmb9pQ&embed=true",
+      "lastUpdated": "2026-05-28T01:28:03.366Z"
     },
     "scroll-until-image.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16411272fbc49ea25d679e",
-      "lastUpdated": "2026-05-27T00:55:46.226Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791ac7d423e81b390fab4",
+      "lastUpdated": "2026-05-28T00:51:57.166Z"
     },
     "prompt.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16411372fbc49ea25d679f",
-      "lastUpdated": "2026-05-27T01:09:45.225Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791af7d423e81b390fab5",
+      "lastUpdated": "2026-05-28T01:06:39.358Z"
     },
     "focus-window.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16411472fbc49ea25d67a0",
-      "lastUpdated": "2026-05-27T00:55:49.071Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791b17d423e81b390fab6",
+      "lastUpdated": "2026-05-28T00:52:01.734Z"
     },
     "captcha-api.test.mjs": {
       "url": "https://console.testdriver.ai/runs/698f7df69e27ce1528d7d087/698f7fb0d3b320ad547d9d44",
       "lastUpdated": "2026-02-13T19:55:05.951Z"
     },
     "element-not-found.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16414272fbc49ea25d67a2",
-      "lastUpdated": "2026-05-27T01:10:31.738Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791e07d423e81b390fab8",
+      "lastUpdated": "2026-05-28T01:07:28.823Z"
     },
     "formatted-logging.test.mjs": {
       "url": "https://console-test.testdriver.ai/runs/69c8738614b73310c7839412/69c873a714b73310c7839450",
       "lastUpdated": "2026-03-29T00:36:10.628Z"
     },
     "hover-text.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16417072fbc49ea25d67a4",
-      "lastUpdated": "2026-05-27T00:57:20.040Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1792107d423e81b390faba",
+      "lastUpdated": "2026-05-28T00:53:35.603Z"
     },
     "no-provision.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62b7706a177a05bccd1cf",
       "lastUpdated": "2026-03-03T00:32:25.279Z"
     },
     "ai.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16415872fbc49ea25d67a3",
-      "replayUrl": "https://console-test.testdriver.ai/replay/6a164a834a4688499f88ea61?share=zG4dSiv1EBheV2pYxjSAA",
-      "embedUrl": "https://console-test.testdriver.ai/replay/6a164a834a4688499f88ea61?share=zG4dSiv1EBheV2pYxjSAA&embed=true",
-      "lastUpdated": "2026-05-27T01:36:10.091Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791f87d423e81b390fab9",
+      "replayUrl": "https://console-test.testdriver.ai/replay/6a179ae57d423e81b390fb82?share=keImOYhUmGpWQQFuhIZSaw",
+      "embedUrl": "https://console-test.testdriver.ai/replay/6a179ae57d423e81b390fb82?share=keImOYhUmGpWQQFuhIZSaw&embed=true",
+      "lastUpdated": "2026-05-28T01:31:25.753Z"
     },
     "popup-loading.test.mjs": {
       "url": "https://console.testdriver.ai/runs/698bc89f7140c3fa7daaca8d/698bca7f7140c3fa7daacbf7",
@@ -144,12 +144,12 @@
       "lastUpdated": "2026-02-13T19:55:05.953Z"
     },
     "findall-coffee-icons.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a1640fb72fbc49ea25d679c",
-      "lastUpdated": "2026-05-27T01:02:17.471Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1791927d423e81b390fab2",
+      "lastUpdated": "2026-05-28T00:58:50.726Z"
     },
     "parse.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a163feb72fbc49ea25d66f1/6a16418572fbc49ea25d67a5",
-      "lastUpdated": "2026-05-27T01:11:39.542Z"
+      "url": "https://console-test.testdriver.ai/runs/6a1790707d423e81b390fa89/6a1792297d423e81b390fabb",
+      "lastUpdated": "2026-05-28T01:08:39.338Z"
     },
     "flake-diffthreshold-001.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62bcafc0ac3cc632a91aa",

package/docs/v7/client.mdx

@@ -54,7 +54,11 @@ const testdriver = new TestDriver(apiKey, options)
     </ParamField>
     
     <ParamField path="reconnect" type="boolean" default="false">
-      Reconnect to the last used sandbox instead of creating a new one. When `true`, provision methods (`chrome`, `vscode`, `installer`, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists.
+      Reattach to the last used sandbox instead of creating a new one. When `true`, the SDK reads the sandbox id from `.testdriver/last-sandbox` (written automatically on every successful connect) and rejoins that VM. Provision methods (`chrome`, `vscode`, `installer`, etc.) are skipped because the application is already running. The previous sandbox must still be alive — see [`keepAlive`](#keepalive) and the [Machine Setup guide](/v7/machine-setup#keeping-machines-alive-between-runs).
+    </ParamField>
+
+    <ParamField path="sandboxId" type="string">
+      Reattach to a specific sandbox id instead of the one recorded in `.testdriver/last-sandbox`. Use this for CI matrices or to pin a chain of tests to a known VM. Implies `reconnect: true` behavior (provision calls are skipped).
     </ParamField>
     
     <ParamField path="preview" type="string" default="browser">

package/docs/v7/examples/ai.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* ai.test.mjs output */}
 <iframe 
-  src="https://console-test.testdriver.ai/replay/6a164a834a4688499f88ea61?share=zG4dSiv1EBheV2pYxjSAA&embed=true" 
+  src="https://console-test.testdriver.ai/replay/6a179ae57d423e81b390fb82?share=keImOYhUmGpWQQFuhIZSaw&embed=true" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/assert.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* assert.test.mjs output */}
 <iframe 
-  src="https://console-test.testdriver.ai/replay/6a164876cdb57a637d2faabd?share=P6veCnmKhjRh1lJK7aMx4g&embed=true" 
+  src="https://console-test.testdriver.ai/replay/6a1798e07d423e81b390fb43?share=UqiUSmkhK2HQemcBtpVI3w&embed=true" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/chrome-extension.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* chrome-extension.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a16400272fbc49ea25d6713/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1790897d423e81b390fa98/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/element-not-found.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* element-not-found.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a16414272fbc49ea25d67a2/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1791e07d423e81b390fab8/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/findall-coffee-icons.mdx

@@ -18,7 +18,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* findall-coffee-icons.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1640fb72fbc49ea25d679c/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1791927d423e81b390fab2/replay" 
   width="100%" 
   height="600" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/hover-image.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* hover-image.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a16406072fbc49ea25d6784/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1790ee7d423e81b390faab/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/hover-text-with-description.mdx

@@ -18,7 +18,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* hover-text-with-description.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a16401b72fbc49ea25d672e/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1790a37d423e81b390fa9e/replay" 
   width="100%" 
   height="600" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/hover-text.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* hover-text.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a16417072fbc49ea25d67a4/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1792107d423e81b390faba/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/installer.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* installer.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a16408272fbc49ea25d6790/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1791107d423e81b390faac/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/launch-vscode-linux.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* launch-vscode-linux.test.mjs output */}
 <iframe 
-  src="https://console-test.testdriver.ai/replay/6a16461acdb57a637d2faaad?share=FN1SuaLYCODCJGkQQDUsQ&embed=true" 
+  src="https://console-test.testdriver.ai/replay/6a1796cd7d423e81b390faed?share=vC6J7mIobNeQqdUdiZog&embed=true" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/parse.mdx

@@ -18,7 +18,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* parse.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a16418572fbc49ea25d67a5/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1792297d423e81b390fabb/replay" 
   width="100%" 
   height="600" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/press-keys.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* press-keys.test.mjs output */}
 <iframe 
-  src="https://console-test.testdriver.ai/replay/6a164834cdb57a637d2faabb?share=shwxxjLJAs6ja39RQGXcTA&embed=true" 
+  src="https://console-test.testdriver.ai/replay/6a1798a77d423e81b390fb3c?share=HWIAWhrv9Umwbyi641bgg&embed=true" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/scroll-keyboard.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* scroll-keyboard.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a16411072fbc49ea25d679d/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1791aa7d423e81b390fab3/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/scroll.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* scroll.test.mjs output */}
 <iframe 
-  src="https://console-test.testdriver.ai/replay/6a1649b84a4688499f88ea5d?share=gCsly4DGt4iQxlIjhHiceg&embed=true" 
+  src="https://console-test.testdriver.ai/replay/6a179a1b7d423e81b390fb6c?share=LaHVFvjLtWSJbRzmb9pQ&embed=true" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/type.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* type.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1640b772fbc49ea25d6799/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a1791497d423e81b390faaf/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/machine-setup.mdx

@@ -87,6 +87,16 @@ const testdriver = TestDriver(context, {
 
 Windows (and Linux) cold starts can be expensive if you're iterating quickly. Use `keepAlive` + `reconnect` to reuse the same VM across multiple test runs.
 
+### How it works
+
+Every time the SDK successfully connects to a sandbox, it records the sandbox id in `.testdriver/last-sandbox` inside your project directory. The next test that opts in with `reconnect: true` reads that file and reattaches automatically — no manual id tracking required.
+
+Provision calls (`testdriver.provision.chrome(...)`, `vscode(...)`, etc.) are **skipped** when reconnecting, because the application is already running inside the sandbox from the previous run.
+
+<Note>
+  `.testdriver/last-sandbox` is already covered by the default TestDriver `.gitignore`. Don't commit it.
+</Note>
+
 ### Step 1 — Start the machine with a long `keepAlive`
 
 ```javascript
@@ -102,30 +112,87 @@ await testdriver.provision.chrome({ url: "https://example.com" });
 
 When this test finishes, the sandbox stays running for 30 minutes instead of being terminated immediately.
 
-### Step 2 — Connect in subsequent runs
+### Step 2 — Reattach automatically with `reconnect: true`
 
 ```javascript
 // second.test.mjs
 const testdriver = TestDriver(context, {
   os: "windows",
+  reconnect: true,            // ← reads .testdriver/last-sandbox
   keepAlive: 30 * 60 * 1000,
 });
 
-await testdriver.connect({ sandboxId: "sandbox-abc123" });
-
-// provision.chrome() is automatically skipped — Chrome is already open
+// No provision call — Chrome is already open from the previous run.
 await testdriver.find("Sign In button").click();
 ```
 
-When connecting to an existing sandbox ID:
+### Step 2 (alternative) — Reattach to an explicit id
+
+If you need to pin to a specific sandbox (CI matrix, multiple chains in parallel, etc.) pass the id directly:
+
+```javascript
+await testdriver.connect({ sandboxId: "sandbox-abc123" });
+```
+
+When reattaching to a sandbox:
 - You reuse a specific running machine directly
-- You can continue from the app state created in an earlier test run
-- You should run within the previous test's `keepAlive` window
+- You continue from the app state created in the earlier run
+- You must run within the previous test's `keepAlive` window
 
 <Tip>
-  You can also supply a sandbox ID directly: `await testdriver.connect({ sandboxId: "sandbox-abc123" })`. Use `testdriver.getLastSandboxId()` to retrieve the ID of the last sandbox for scripting purposes.
+  Use `testdriver.getLastSandboxId()` to read the recorded sandbox id (and optional metadata) for scripting purposes.
 </Tip>
 
+### Chaining describe blocks within one test file
+
+A common pattern is to break a long flow into focused `describe` blocks that share one sandbox — the first block provisions and signs in, later blocks reconnect and continue:
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+const KEEP_ALIVE_MS = 5 * 60 * 1000;
+
+describe("step 1 — log in", () => {
+  it("signs in and lands on the dashboard", async (context) => {
+    const testdriver = TestDriver(context, { keepAlive: KEEP_ALIVE_MS });
+    await testdriver.provision.chrome({ url: "https://example.com/login" });
+    await testdriver.find("username input").click();
+    await testdriver.type("standard_user");
+    await testdriver.pressKeys(["tab"]);
+    await testdriver.type("secret_sauce", { secret: true });
+    await testdriver.pressKeys(["enter"]);
+    expect(await testdriver.assert("the dashboard is visible")).toBeTruthy();
+  });
+});
+
+describe("step 2 — add to cart", () => {
+  it("reuses the logged-in sandbox", async (context) => {
+    const testdriver = TestDriver(context, {
+      reconnect: true,           // ← skip provisioning, reattach
+      keepAlive: KEEP_ALIVE_MS,
+    });
+    await testdriver.find("Add to cart").click();
+    await testdriver.find("cart icon").click();
+    expect(await testdriver.assert("the cart has an item")).toBeTruthy();
+  });
+});
+
+describe("step 3 — check out", () => {
+  it("continues from the cart state", async (context) => {
+    const testdriver = TestDriver(context, { reconnect: true, keepAlive: 30_000 });
+    await testdriver.find("Checkout").click();
+    expect(await testdriver.assert("the checkout form is visible")).toBeTruthy();
+  });
+});
+```
+
+A runnable copy of this pattern lives at [`examples/reconnect-sequential.test.mjs`](https://github.com/testdriverai/mono/blob/main/sdk/examples/reconnect-sequential.test.mjs).
+
+<Warning>
+  Vitest runs **test files** in parallel by default. Within a single file, `describe`/`it` blocks run in source order, so reconnect chaining works as written. To chain across multiple files, run them sequentially (e.g. `vitest run --sequence.concurrent=false` or place them in a single project pool with workers set to 1).
+</Warning>
+
 ### How `keepAlive` works
 
 `keepAlive` is a duration in milliseconds. After the SDK disconnects, the server keeps the VM running for that long before terminating it. The default is `60000` (1 minute). Note: `keepAlive: 0` currently falls back to the default disconnect grace period rather than terminating immediately, so use a positive duration when you want to control the grace window explicitly.

package/examples/config.mjs

@@ -1,4 +1,5 @@
 export const getDefaults = (context) => ({
   ip: context.ip || process.env.TD_IP,
   preview: 'web',
+  cache: 'false'
 });

package/lib/core/Dashcam.js

@@ -150,6 +150,34 @@ class Dashcam {
 
   }
 
+  /**
+   * Workaround for dashcam <1.5.0: webLogsDaemon.js writes its state to a
+   * `.dashcam` directory relative to process.cwd(). When launched by the
+   * runner, cwd is /usr/lib/node_modules/@testdriverai/runner (root-owned),
+   * so the daemon can't mkdir its state dir as user `user` and silently
+   * dies — recordings never start (or `dashcam logs --add` fails with EACCES).
+   * Pre-create world-writable .dashcam dirs at both the current cwd and the
+   * known global-install path so the daemon survives regardless of which path
+   * dashcam ends up using. Must run before ANY dashcam invocation, not just
+   * auth(), because addWebLog() is called before start()/auth() in provision.
+   * TODO: remove once dashcam >=1.5.0 (which uses $HOME) is bundled.
+   * @private
+   */
+  async _ensureDashcamStateDirs() {
+    if (this.client.os === "windows") return;
+    if (!this._dashcamDirsReady) {
+      this._dashcamDirsReady = this.client.exec(
+        this._getShell(),
+        `sudo mkdir -p "$(pwd)/.dashcam" /usr/lib/node_modules/@testdriverai/runner/.dashcam 2>/dev/null; ` +
+          `sudo chmod 0777 "$(pwd)/.dashcam" /usr/lib/node_modules/@testdriverai/runner/.dashcam 2>/dev/null; ` +
+          `true`,
+        10000,
+        process.env.TD_DEBUG == "true" ? false : true,
+      );
+    }
+    await this._dashcamDirsReady;
+  }
+
   /**
    * Authenticate dashcam with API key
    * @param {string} [apiKey] - Override API key
@@ -174,23 +202,7 @@ class Dashcam {
       this._log("debug", "Auth output:", authOutput);
     } else {
       // Linux/Mac authentication with TD_API_ROOT
-
-      // Workaround for dashcam <1.5.0: webLogsDaemon.js writes its state to a
-      // `.dashcam` directory relative to process.cwd(). When launched by the
-      // runner, cwd is /usr/lib/node_modules/@testdriverai/runner (root-owned),
-      // so the daemon can't mkdir its state dir as user `user` and silently
-      // dies — recordings never start. Pre-create world-writable .dashcam dirs
-      // at both the current cwd and the known global-install path so the
-      // daemon survives regardless of which path dashcam ends up using.
-      // TODO: remove once dashcam >=1.5.0 (which uses $HOME) is bundled.
-      await this.client.exec(
-        shell,
-        `sudo mkdir -p "$(pwd)/.dashcam" /usr/lib/node_modules/@testdriverai/runner/.dashcam 2>/dev/null; ` +
-          `sudo chmod 0777 "$(pwd)/.dashcam" /usr/lib/node_modules/@testdriverai/runner/.dashcam 2>/dev/null; ` +
-          `true`,
-        10000,
-        process.env.TD_DEBUG == "true" ? false : true,
-      );
+      await this._ensureDashcamStateDirs();
 
       const authOutput = await this.client.exec(
         shell,
@@ -233,6 +245,7 @@ class Dashcam {
       );
       this._log("debug", "Add log tracking output:", addLogOutput);
     } else {
+      await this._ensureDashcamStateDirs();
       // Create log file
       await this.client.exec(
         shell,
@@ -272,6 +285,7 @@ class Dashcam {
       );
       this._log("debug", "Add application log tracking output:", addLogOutput);
     } else {
+      await this._ensureDashcamStateDirs();
       const addLogOutput = await this.client.exec(
         shell,
         `TD_API_ROOT="${apiRoot}" dashcam logs --add --type=application --application="${application}" --name="${name}"`,
@@ -306,6 +320,7 @@ class Dashcam {
         this._log("warn", "Add web log tracking failed:", err.message);
       }
     } else {
+      await this._ensureDashcamStateDirs();
       const addLogOutput = await this.client.exec(
         shell,
         `TD_API_ROOT="${apiRoot}" dashcam logs --add --type=web --pattern="${pattern}" --name="${name}"`,
@@ -386,6 +401,7 @@ class Dashcam {
       this._log("debug", "Dashcam recording started");
     } else {
       // Linux/Mac with TD_API_ROOT
+      await this._ensureDashcamStateDirs();
       this._log("debug", "Starting dashcam recording on Linux/Mac...");
       const dashcamPath = await this._getDashcamPath();
       const titleArg = this.title

package/package.json

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

package/sdk.d.ts

@@ -277,8 +277,10 @@ export interface TestDriverOptions {
   e2bTemplateId?: string;
   /** Cache key for element finding operations. If provided, enables caching tied to this key */
   cacheKey?: string;
-  /** Reconnect to the last used sandbox instead of creating a new one. When true, provision methods (chrome, vscode, installer, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists. */
+  /** Reconnect to the last used sandbox instead of creating a new one. When true, provision methods (chrome, vscode, installer, etc.) will be skipped since the application is already running. Looks up the sandbox id from `.testdriver/last-sandbox` if `sandboxId` is not also provided. */
   reconnect?: boolean;
+  /** Explicit sandbox id to reconnect to. Implies `newSandbox: false` unless explicitly overridden. */
+  sandboxId?: string;
   /** Enable/disable Dashcam video recording (default: true) */
   dashcam?: boolean;
   /**
@@ -1042,15 +1044,15 @@ export default class TestDriverSDK {
   disconnect(): Promise<void>;
 
   /**
-   * Get the last sandbox info from the stored file
+   * Get info about the most recently provisioned sandbox (from this SDK instance
+   * if connected, otherwise read from `.testdriver/last-sandbox`).
    * @returns Last sandbox info or null if not found
    */
   getLastSandboxId(): {
-    sandboxId: string | null;
-    os: "windows" | "linux";
-    ami: string | null;
-    instanceType: string | null;
-    timestamp: string | null;
+    sandboxId: string;
+    os?: "windows" | "linux";
+    e2bTemplateId?: string | null;
+    createdAt?: number;
   } | null;
 
   // Element Finding API

package/sdk.js

@@ -1510,6 +1510,21 @@ class TestDriverSDK {
     this.reconnect =
       options.reconnect !== undefined ? options.reconnect : false;
 
+    // Explicit sandbox id to reconnect to (overrides last-sandbox file)
+    this.sandboxId = options.sandboxId || null;
+
+    // When reconnect is requested, an explicit sandboxId implies newSandbox=false.
+    // If reconnect:true but no sandboxId given, try to load from .testdriver/last-sandbox.
+    if (this.reconnect && !this.sandboxId) {
+      const last = TestDriverSDK._readLastSandbox();
+      if (last && last.sandboxId) {
+        this.sandboxId = last.sandboxId;
+      }
+    }
+    if (this.sandboxId && options.newSandbox === undefined) {
+      this.newSandbox = false;
+    }
+
     // Store keepAlive preference from options
     this.keepAlive =
       options.keepAlive !== undefined ? options.keepAlive : undefined;
@@ -2070,6 +2085,9 @@ CAPTCHA_SOLVER_EOF`,
     // Set agent properties for buildEnv to use
     if (connectOptions.sandboxId) {
       this.agent.sandboxId = connectOptions.sandboxId;
+    } else if (this.sandboxId) {
+      // Constructor-provided sandboxId (explicit or loaded from .testdriver/last-sandbox)
+      this.agent.sandboxId = this.sandboxId;
     }
     // Use IP from connectOptions if provided, otherwise fall back to constructor IP
     if (connectOptions.ip !== undefined) {
@@ -2168,6 +2186,20 @@ CAPTCHA_SOLVER_EOF`,
       sandboxId: this.instance?.instanceId,
     });
 
+    // Persist the active sandbox id so a later run with `reconnect: true`
+    // can reattach without the caller having to thread the id through.
+    const activeSandboxId =
+      this.instance?.sandboxId || this.instance?.instanceId || null;
+    if (activeSandboxId) {
+      this.sandboxId = activeSandboxId;
+      TestDriverSDK._writeLastSandbox({
+        sandboxId: activeSandboxId,
+        os: this.os,
+        e2bTemplateId: this.e2bTemplateId || null,
+        createdAt: Date.now(),
+      });
+    }
+
     return this.instance;
   }
 
@@ -3645,6 +3677,52 @@ CAPTCHA_SOLVER_EOF`,
   clearLogs() {
     this._logBuffer = [];
   }
+
+  /**
+   * Return info about the most recently provisioned sandbox (from this process
+   * or persisted from a previous run via .testdriver/last-sandbox).
+   * @returns {{ sandboxId: string, os?: string, e2bTemplateId?: string|null, createdAt?: number } | null}
+   */
+  getLastSandboxId() {
+    if (this.sandboxId) {
+      return {
+        sandboxId: this.sandboxId,
+        os: this.os,
+        e2bTemplateId: this.e2bTemplateId || null,
+      };
+    }
+    return TestDriverSDK._readLastSandbox();
+  }
+
+  /** @private */
+  static _lastSandboxPath() {
+    return path.join(process.cwd(), ".testdriver", "last-sandbox");
+  }
+
+  /** @private */
+  static _readLastSandbox() {
+    try {
+      const p = TestDriverSDK._lastSandboxPath();
+      if (!fs.existsSync(p)) return null;
+      const raw = fs.readFileSync(p, "utf8");
+      const data = JSON.parse(raw);
+      if (!data || !data.sandboxId) return null;
+      return data;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /** @private */
+  static _writeLastSandbox(data) {
+    try {
+      const p = TestDriverSDK._lastSandboxPath();
+      fs.mkdirSync(path.dirname(p), { recursive: true });
+      fs.writeFileSync(p, JSON.stringify(data, null, 2));
+    } catch (_) {
+      // Best-effort — don't fail the test if we can't persist.
+    }
+  }
 }
 
 // Expose SDK version as a static property for use by vitest hooks/plugins