@mastra/platform-workspace 1.1.1-alpha.0 → 1.2.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @mastra/platform
 
+## 1.2.0-alpha.2
+
+### Minor Changes
+
+- Added startup observability to `PlatformSandbox`. New optional `sessionId` and `threadId` options let you correlate all sandbox startup activity with the session that triggered it, and the sandbox now logs how long startup took and whether it became reachable. ([#21189](https://github.com/mastra-ai/mastra/pull/21189))
+
+  ```ts
+  import { PlatformSandbox } from '@mastra/platform-workspace';
+
+  const sandbox = new PlatformSandbox({
+    projectId: 'proj_123',
+    environmentId: 'env_123',
+    sessionId: 'session_abc', // correlate startup logs with your session
+    threadId: 'thread_xyz', // optional finer-grained correlation
+  });
+  ```
+
+- Added `PlatformSandbox.snapshot()` to capture the configured recovery checkpoint. ([#21221](https://github.com/mastra-ai/mastra/pull/21221))
+
+  ```ts
+  await sandbox.snapshot();
+  ```
+
+### Patch Changes
+
+- Fixed Platform Sandbox startup so commands use a reliable connection while a new sandbox is starting. ([#21028](https://github.com/mastra-ai/mastra/pull/21028))
+
+- Updated dependencies [[`9571e3a`](https://github.com/mastra-ai/mastra/commit/9571e3a06ed2c5220196460bf82a2129255c3a8b), [`d6c56f9`](https://github.com/mastra-ai/mastra/commit/d6c56f951db3213330b98b0abafa9778c8770e58), [`9571e3a`](https://github.com/mastra-ai/mastra/commit/9571e3a06ed2c5220196460bf82a2129255c3a8b), [`acc3513`](https://github.com/mastra-ai/mastra/commit/acc3513b19f79bf0a7ec2998694580edca54086c), [`94e7ae9`](https://github.com/mastra-ai/mastra/commit/94e7ae970b37c888cd1244ef013292639a2fe6d1), [`6a667b4`](https://github.com/mastra-ai/mastra/commit/6a667b4b7cd6a93fe41fcdd357b08c5a8c09b9ab), [`2440e09`](https://github.com/mastra-ai/mastra/commit/2440e096ea6c2def1ccc1eb2d0f3f5b88c4af940), [`a59049b`](https://github.com/mastra-ai/mastra/commit/a59049b1652a13efff66ac826326b5ed9a550342)]:
+  - @mastra/core@1.58.0-alpha.13
+
+## 1.2.0-alpha.1
+
+### Minor Changes
+
+- Split `PlatformSandbox.stop()` from `PlatformSandbox.destroy()` so the two lifecycle exits mirror `@mastra/railway` `RailwaySandbox` ([#20956](https://github.com/mastra-ai/mastra/pull/20956))
+
+  **Before:** `stop()` was an alias for `destroy()`, and `destroy()` only released the sandbox VM — the on-provider recovery checkpoint was never actively deleted. There was no way to end a hosted sandbox while preserving its checkpoint for a later resume, and destroyed sandboxes accumulated stray checkpoints until the upstream provider's own GC.
+
+  **After:**
+
+  - **`stop()`** — releases the VM but **preserves the recovery checkpoint**. Any in-flight capture is awaited first so the preserved checkpoint reflects the caller's latest state. Corresponds to `DELETE /v1/projects/:pid/sandbox/:sandboxId` on workspace-proxy, which by contract does not touch the checkpoint.
+  - **`destroy()`** — releases the VM **and deletes the recovery checkpoint**. Cancels any in-flight capture (no reason to burn a capture on state we're releasing), asks the proxy to delete the checkpoint via `DELETE /v1/projects/:pid/sandbox/:sandboxId/checkpoint`, then releases the VM. Both remote operations are best-effort — an already-absent checkpoint or a transient checkpoint-delete failure does not block the VM teardown, since a half-torn-down sandbox is worse than a lingering checkpoint alone.
+
+  Callers constructed without a recovery `id` skip the checkpoint DELETE and behave identically to `stop()`, because they have no on-provider checkpoint to release.
+
+  This restores the "providers move in lockstep" invariant that broke after `@mastra/railway` gained its own `stop()`/`destroy()` split.
+
+  **Requires** a matching workspace-proxy release that exposes `DELETE /v1/projects/:pid/sandbox/:sandboxId/checkpoint`. Callers on older workspace-proxy versions will see the checkpoint DELETE 404 and fall through to the VM DELETE — same net effect as the pre-split behavior.
+
+### Patch Changes
+
+- Add public `captureCheckpoint()` method to `PlatformSandbox` — mirrors `@mastra/railway`'s `RailwaySandbox.captureCheckpoint()` so callers (e.g. a factory-side scheduler) can capture the recovery checkpoint on demand at semantic moments (turn end, session-idle, pre-teardown) without having to know which provider is underneath. ([#20882](https://github.com/mastra-ai/mastra/pull/20882))
+
+  ```ts
+  const result = await sandbox.captureCheckpoint();
+  switch (result.status) {
+    case 'captured':
+    case 'coalesced':
+      await persistBinding({ sessionId, checkpointName: result.checkpointName });
+      break;
+    case 'skipped':
+      // result.reason: 'no-checkpoint-name-configured' | 'sandbox-not-running'
+      break;
+  }
+  ```
+
+  - POSTs to `/v1/projects/:projectId/sandbox/:sandboxId/checkpoint` with the caller-supplied recovery key (the `id` the sandbox was constructed with) as the body, matching the shape the workspace-proxy expects.
+  - Coalesces concurrent callers on the same instance onto a single upstream request, so N simultaneous turn-end fires do not each round-trip the proxy.
+  - Returns `{ status: 'skipped', reason: 'no-checkpoint-name-configured' }` when the sandbox was constructed without a caller-supplied `id` (an auto-generated random id is never a meaningful recovery key), and `{ status: 'skipped', reason: 'sandbox-not-running' }` when the sandbox has not been started yet.
+  - Normalizes upstream "sandbox destroyed" outcomes (a 410 from the proxy, or the proxy's own `skipped` status) to `{ status: 'skipped', reason: 'sandbox-not-running' }` — the discriminant matches the pre-flight case so callers branch uniformly, and the sandbox's local state is cleared as a side effect so the next `start()` provisions fresh instead of reattaching to a dead id.
+  - Transport failures other than 410 (5xx, 429) propagate as `PlatformApiError` for the caller to handle.
+
+- Coalesce concurrent `PlatformSandbox.start()` callers onto a single in-flight attempt ([#20960](https://github.com/mastra-ai/mastra/pull/20960))
+
+  Two callers hitting `start()` on the same instance before the first one resolves used to both race to `POST /v1/projects/:pid/sandbox` (or `GET /sandbox/:id` on the reattach path), burning N proxy provisions and leaving `N-1` stray sandboxes behind. Fleet-level coalescing on the caller side masked most of this, but the underlying invariant "providers move in lockstep" was false — `@mastra/railway` `RailwaySandbox` has always had `_startInFlight` coalescing.
+
+  `start()` now publishes a single shared promise via `??=` **before** the first `await`, so a second caller entering `start()` while the first is mid-round-trip joins the existing promise instead of racing past the null check. The slot is cleared in `.finally()` on both success and failure paths so a failed attempt isn't a permanent latch — the next call starts fresh. Failures propagate to every joined caller.
+
+  Bug fix; no public API surface change. Callers already awaiting `start()` see the same success/failure semantics; the only observable difference is one upstream call instead of N.
+
+- Updated dependencies [[`cdd5c33`](https://github.com/mastra-ai/mastra/commit/cdd5c33ac6c7118a9f139e6dc0e14e6a8ae31658), [`d7cf7fa`](https://github.com/mastra-ai/mastra/commit/d7cf7fafc1ae1b50bd8462dd0e6c671a8606db93), [`0f9a448`](https://github.com/mastra-ai/mastra/commit/0f9a448502157e59f7b76f24360ad497168f5ef8), [`289f4ce`](https://github.com/mastra-ai/mastra/commit/289f4ce16e3293370440172132c52ee787cbc09f), [`4f16ff8`](https://github.com/mastra-ai/mastra/commit/4f16ff824bf2f9b0ddc93f210477c10c8a4fb1ab), [`1c67d85`](https://github.com/mastra-ai/mastra/commit/1c67d85e9da8285662f4dbbf47e0378c3fee0747), [`ba24be6`](https://github.com/mastra-ai/mastra/commit/ba24be662439c331ab23a600041f93803c89eca8), [`842b5fe`](https://github.com/mastra-ai/mastra/commit/842b5fe22b6a7fa811bd14e48eb9af523ac989f2), [`80bdf3a`](https://github.com/mastra-ai/mastra/commit/80bdf3ae16ade6ff63bde0cb16fa2df8ab7dd4dd), [`9ba1247`](https://github.com/mastra-ai/mastra/commit/9ba12470c77f1c03642d720ce67e517e878f666e), [`fd96298`](https://github.com/mastra-ai/mastra/commit/fd96298a8367622f4ebfcaa97b5b6c1fbbd14564), [`6a84954`](https://github.com/mastra-ai/mastra/commit/6a84954a2667f85b6d59da652dab1bbff007ccb0), [`52d8ef0`](https://github.com/mastra-ai/mastra/commit/52d8ef03801f1deb7ee48532fc4190dd4a33916c), [`cdd5c33`](https://github.com/mastra-ai/mastra/commit/cdd5c33ac6c7118a9f139e6dc0e14e6a8ae31658), [`efd5c81`](https://github.com/mastra-ai/mastra/commit/efd5c81cc25fde3c2ddd86fc1178deb4ec176e19), [`0976933`](https://github.com/mastra-ai/mastra/commit/0976933142333ec78451feef265b68bcb45aa5e7), [`242b945`](https://github.com/mastra-ai/mastra/commit/242b94558777bfbdeb42cbfea84afff0b6ad0633), [`fea5cae`](https://github.com/mastra-ai/mastra/commit/fea5caedc7e2cfea51784a15e015952692027abf), [`4b59f78`](https://github.com/mastra-ai/mastra/commit/4b59f786cbc9a7d1ef07a07517dbd4b96865e99d), [`7010c5d`](https://github.com/mastra-ai/mastra/commit/7010c5d15728bf9c5dfe4fb6b1bf80ce23bf143a)]:
+  - @mastra/core@1.58.0-alpha.3
+
 ## 1.1.1-alpha.0
 
 ### Patch Changes

package/dist/client.d.ts

@@ -1,6 +1,19 @@
 export interface PlatformClientOptions {
     accessToken?: string;
     projectId?: string;
+    /**
+     * Advisory correlation id for the factory session driving this client.
+     * Sent as `x-mastra-session-id` on every proxy request so proxy-side logs
+     * can be joined back to the calling session without a multi-store hand-join
+     * (`threadId → sessionId → sandboxId → providerResourceId`). Never used for
+     * authorization — the Bearer token remains the only credential.
+     */
+    sessionId?: string;
+    /**
+     * Advisory correlation id for the factory thread, sent as
+     * `x-mastra-thread-id` when present. See {@link PlatformClientOptions.sessionId}.
+     */
+    threadId?: string;
     fetch?: typeof fetch;
 }
 export interface PlatformRequestOptions extends RequestInit {
@@ -11,6 +24,8 @@ export declare function resolvePlatformOptions(options: PlatformClientOptions):
     accessToken: string;
     projectId: string;
     proxyUrl: string;
+    sessionId: string | undefined;
+    threadId: string | undefined;
     fetch: typeof fetch;
 };
 /**
@@ -37,6 +52,10 @@ export declare class PlatformClient {
     readonly accessToken: string;
     readonly projectId: string;
     readonly proxyUrl: string;
+    /** Advisory session correlation id — see {@link PlatformClientOptions.sessionId}. */
+    readonly sessionId: string | undefined;
+    /** Advisory thread correlation id — see {@link PlatformClientOptions.threadId}. */
+    readonly threadId: string | undefined;
     readonly fetch: typeof fetch;
     constructor(options: PlatformClientOptions);
     request(path: string, options?: PlatformRequestOptions): Promise<Response>;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;CAC/D;AAWD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB;;;;;EAOpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAC;CACd;AAkBD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2HAA2H;IAC3H,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,yGAAyG;IACzG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE9B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAUzC;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;gBAEjB,OAAO,EAAE,qBAAqB;IAQpC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,QAAQ,CAAC;CAoBrF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;CAC/D;AAWD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB;;;;;;;EASpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAC;CACd;AAkBD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2HAA2H;IAC3H,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,yGAAyG;IACzG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE9B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAUzC;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;gBAEjB,OAAO,EAAE,qBAAqB;IAUpC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,QAAQ,CAAC;CA0BrF"}

package/dist/index.cjs

@@ -42,6 +42,8 @@ function resolvePlatformOptions(options) {
 		accessToken: requireOption(options.accessToken ?? process.env.MASTRA_PLATFORM_ACCESS_TOKEN, "accessToken"),
 		projectId: requireOption(options.projectId ?? process.env.MASTRA_PROJECT_ID, "projectId"),
 		proxyUrl: (process.env.MASTRA_WORKSPACE_PROXY_URL ?? DEFAULT_PROXY_URL).replace(/\/$/, ""),
+		sessionId: options.sessionId,
+		threadId: options.threadId,
 		fetch: options.fetch ?? fetch
 	};
 }
@@ -85,12 +87,18 @@ var PlatformClient = class {
 	accessToken;
 	projectId;
 	proxyUrl;
+	/** Advisory session correlation id — see {@link PlatformClientOptions.sessionId}. */
+	sessionId;
+	/** Advisory thread correlation id — see {@link PlatformClientOptions.threadId}. */
+	threadId;
 	fetch;
 	constructor(options) {
 		const resolved = resolvePlatformOptions(options);
 		this.accessToken = resolved.accessToken;
 		this.projectId = resolved.projectId;
 		this.proxyUrl = resolved.proxyUrl;
+		this.sessionId = resolved.sessionId;
+		this.threadId = resolved.threadId;
 		this.fetch = resolved.fetch;
 	}
 	async request(path, options = {}) {
@@ -98,6 +106,8 @@ var PlatformClient = class {
 		for (const [key, value] of Object.entries(options.query ?? {})) if (value !== void 0) url.searchParams.set(key, String(value));
 		const headers = new Headers(options.headers);
 		headers.set("authorization", `Bearer ${this.accessToken}`);
+		if (this.sessionId) headers.set("x-mastra-session-id", this.sessionId);
+		if (this.threadId) headers.set("x-mastra-thread-id", this.threadId);
 		const { query: _query, ...fetchOptions } = options;
 		const signal = fetchOptions.signal ?? AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS);
 		const response = await this.fetch(url, {
@@ -693,6 +703,24 @@ const CREATE_MAX_ATTEMPTS = 3;
 /** Base delay between create retries; multiplied by the attempt number. */
 const CREATE_RETRY_BASE_DELAY_MS = 2e3;
 /**
+* How long to wait for the in-sandbox sidecar's `/health` endpoint to respond
+* before giving up and leaving the address registry unpopulated (execs fall
+* back to the lease path). This bounds the fire-and-forget probe that runs
+* after `start()` resolves; the sandbox is usable immediately — the probe
+* only controls whether early execs go via private-net or lease.
+*/
+const SIDECAR_PROBE_TIMEOUT_MS = 3e4;
+/** Delay between sidecar probe attempts. */
+const SIDECAR_PROBE_INTERVAL_MS = 250;
+/**
+* How long `executeCommand` waits for the transport to become ready before
+* falling back to the lease path. This is much shorter than
+* `SIDECAR_PROBE_TIMEOUT_MS` because we want execs to proceed quickly if
+* the sidecar is slow to boot — the probe continues in the background and
+* later execs will use private-net once it succeeds.
+*/
+const TRANSPORT_READY_WAIT_MS = 5e3;
+/**
 * Diagnostic error thrown when the direct-exec WebSocket transport fails
 * twice in a row (opening handshake refused or socket closed mid-stream
 * without an `exit` frame). Distinguishes "the sandbox transport is broken"
@@ -858,12 +886,58 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* Cleared (regardless of success or failure) when the request settles.
 	*/
 	_leaseInFlight = null;
+	/**
+	* True when this sandbox was constructed with a caller-supplied `id` (the
+	* recovery key the proxy hashes into an on-provider checkpoint name).
+	* `captureCheckpoint()` needs this to distinguish "no checkpoint intent"
+	* (auto-generated random id — capture would land under a name no future
+	* boot would look for) from "capture on demand". Cloned sandboxes route
+	* `checkpointName` through `id`, so both entry points set this the same
+	* way.
+	*/
+	_hasRecoveryKey;
+	/**
+	* In-flight `captureCheckpoint()` request. Concurrent callers on the same
+	* instance coalesce onto this single promise so we don't burn N `POST
+	* /checkpoint` round-trips when the fleet fires several turn-end captures
+	* before the first one resolves. Cleared when the request settles.
+	*/
+	_captureInFlight = null;
+	/**
+	* In-flight `start()` attempt. Concurrent callers on a fresh instance
+	* coalesce onto this single promise so a `POST /sandbox` is not fired
+	* N times when N fleet callers race to bring the same logical sandbox
+	* up. Published **synchronously** with `??=` before the first `await`
+	* so a later caller cannot slip through the null check while the
+	* originator is mid-round-trip. Cleared when the shared attempt
+	* settles (success or failure) so the next call sees a clean slot.
+	*
+	* Mirrors OSS `@mastra/railway` `RailwaySandbox._startInFlight`.
+	*/
+	_startInFlight = null;
+	/**
+	* Generation token for the sidecar probe. Incremented on every `start()`
+	* and on teardown. The probe captures this value when it begins; if the
+	* generation has changed by the time the probe succeeds, the probe skips
+	* the `set()` to avoid re-populating a deleted or superseded sandbox entry.
+	*/
+	_probeGeneration = 0;
+	/**
+	* In-flight sidecar probe promise. Concurrent `executeCommand` callers that
+	* arrive before the registry is populated all await this single promise so
+	* we don't fire N independent lease requests during the sidecar boot window.
+	* Once the probe resolves (success or timeout), callers check the registry
+	* and proceed — either via private-net (probe succeeded) or via lease (probe
+	* failed/timed out, but now coalesced via `_leaseInFlight`).
+	*/
+	_transportReadyPromise = null;
 	constructor(options = {}) {
 		super({
 			...options,
 			name: "PlatformSandbox",
 			processes: new PlatformProcessManager()
 		});
+		this._hasRecoveryKey = options.id !== void 0;
 		this.id = options.id ?? this.generateId();
 		this._client = new PlatformClient(options);
 		this._environmentId = options.environmentId ?? process.env.MASTRA_ENVIRONMENT_ID ?? "";
@@ -899,6 +973,8 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			...id !== void 0 && { id },
 			accessToken: this._client.accessToken,
 			projectId: this._client.projectId,
+			...this._client.sessionId !== void 0 && { sessionId: this._client.sessionId },
+			...this._client.threadId !== void 0 && { threadId: this._client.threadId },
 			fetch: this._client.fetch,
 			environmentId: this._environmentId,
 			...options.sandboxId !== void 0 && { sandboxId: options.sandboxId },
@@ -913,11 +989,31 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		});
 	}
 	async start() {
+		this._startInFlight ??= this._doStart().finally(() => {
+			this._startInFlight = null;
+		});
+		return this._startInFlight;
+	}
+	/**
+	* The single `start` attempt behind {@link start}'s coalescing wrapper.
+	*
+	* Split out so the wrapper can install a shared in-flight promise
+	* synchronously (before the first `await`) without inlining the reattach
+	* / retry logic. Joined callers observe whatever outcome this method
+	* produces — success returns normally, failures propagate to every
+	* awaiter.
+	*/
+	async _doStart() {
+		const startedAt = Date.now();
 		if (this._sandboxId) try {
-			const json = await (await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
+			const requestStartedAt = Date.now();
+			const response = await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`);
+			const requestMs = Date.now() - requestStartedAt;
+			const json = await response.json();
 			if (!json.destroyedAt) {
 				this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
 				this._populateAddressFromResponse(json);
+				this._logStartComplete(json.id, startedAt, requestMs, "reattach");
 				return;
 			}
 			this._sandboxId = void 0;
@@ -934,6 +1030,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			env: this._env
 		});
 		let response;
+		const requestStartedAt = Date.now();
 		for (let attempt = 1;; attempt++) try {
 			response = await this._client.request("/sandbox", {
 				method: "POST",
@@ -945,10 +1042,32 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			if (!(error instanceof PlatformApiError && error.status >= 500) || attempt >= CREATE_MAX_ATTEMPTS) throw error;
 			await new Promise((resolve) => setTimeout(resolve, CREATE_RETRY_BASE_DELAY_MS * attempt));
 		}
+		const requestMs = Date.now() - requestStartedAt;
 		const json = await response.json();
 		this._sandboxId = json.id;
 		this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
 		this._populateAddressFromResponse(json);
+		this._logStartComplete(json.id, startedAt, requestMs, "provision");
+	}
+	/**
+	* One timing summary per completed `start()` — the whole
+	* `PlatformSandbox`-visible boot in a single greppable line.
+	*
+	* `requestMs` is the proxy round-trip (`GET /sandbox/:id` on reattach,
+	* `POST /sandbox` including transient-5xx retries on provision) — a black
+	* box from this side that rolls up Railway RPC, sidecar launch, and the
+	* proxy's discovery exec. Sidecar probe cost is intentionally NOT here: the
+	* probe is fire-and-forget and outlives `start()` by design, so its
+	* duration lands on the `platform-workspace probe ok` line instead.
+	*/
+	_logStartComplete(sandboxId, startedAt, requestMs, mode) {
+		this.logger.info("platform-workspace start complete", {
+			sandboxId,
+			sessionId: this._client.sessionId,
+			mode,
+			totalMs: Date.now() - startedAt,
+			requestMs
+		});
 	}
 	/**
 	* Copy `response.instanceUrl` into the injected {@link SandboxAddressRegistry}
@@ -969,20 +1088,274 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	_populateAddressFromResponse(json) {
 		if (!this._addressRegistry) return;
 		if (!json.instanceUrl) return;
-		this._addressRegistry.set(json.id, json.instanceUrl);
+		this._addressRegistry.delete(json.id);
+		const generation = ++this._probeGeneration;
+		this._transportReadyPromise = this._probeSidecarThenRegister(json.id, json.instanceUrl, generation);
+	}
+	/**
+	* Fire-and-forget probe that polls the sidecar's `/health` endpoint until
+	* it responds, then populates the address registry. Runs detached from
+	* `start()` so sandbox provision latency is unchanged; early execs simply
+	* fall back to the lease path until the probe succeeds.
+	*
+	* If the sidecar never comes up within {@link SIDECAR_PROBE_TIMEOUT_MS},
+	* the registry stays unpopulated and all execs go via lease for this
+	* sandbox's lifetime (or until a future `start()` re-runs the probe).
+	*
+	* @param generation - The probe generation captured at call time. If this
+	*   no longer matches `_probeGeneration` when the probe succeeds, the probe
+	*   was superseded by a teardown or a new `start()`, so we skip the `set()`.
+	*/
+	async _probeSidecarThenRegister(sandboxId, instanceUrl, generation) {
+		const probeStartedAt = Date.now();
+		const deadline = probeStartedAt + SIDECAR_PROBE_TIMEOUT_MS;
+		const fetchFn = this._privateNetFetch ?? fetch;
+		let attempts = 0;
+		while (Date.now() < deadline) {
+			if (generation !== this._probeGeneration) return;
+			attempts++;
+			try {
+				const res = await fetchFn(`${instanceUrl}/health`, {
+					method: "GET",
+					signal: AbortSignal.timeout(1e3)
+				});
+				const ok = res.ok;
+				await res.body?.cancel().catch(() => {});
+				if (ok) {
+					this.logger.info("platform-workspace probe ok", {
+						sandboxId,
+						sessionId: this._client.sessionId,
+						probeDurationMs: Date.now() - probeStartedAt,
+						attempts
+					});
+					if (generation === this._probeGeneration && this._sandboxId === sandboxId) this._addressRegistry?.set(sandboxId, instanceUrl);
+					return;
+				}
+			} catch {}
+			await new Promise((r) => setTimeout(r, SIDECAR_PROBE_INTERVAL_MS));
+		}
+		this.logger.warn("platform-workspace probe timed out", {
+			sandboxId,
+			sessionId: this._client.sessionId,
+			timeoutMs: SIDECAR_PROBE_TIMEOUT_MS,
+			attempts
+		});
+	}
+	/**
+	* Wait for the transport to become ready (sidecar probe succeeds) or time
+	* out. Concurrent callers all await the same probe promise, coalescing the
+	* cold-start storm into a single warmup attempt.
+	*
+	* If no probe is in flight (no registry, or registry already populated),
+	* this returns immediately. After the wait (success or timeout), callers
+	* check the registry and proceed — either via private-net or lease. The
+	* lease path is still coalesced via `_leaseInFlight`, so even if the probe
+	* times out, we only mint one lease for all concurrent execs.
+	*/
+	async _awaitTransportReady() {
+		if (this._sandboxId && this._addressRegistry?.get(this._sandboxId)) return;
+		if (!this._transportReadyPromise) return;
+		await Promise.race([this._transportReadyPromise, new Promise((r) => setTimeout(r, TRANSPORT_READY_WAIT_MS))]);
 	}
+	/**
+	* Stop the sandbox while **preserving its recovery checkpoint**.
+	*
+	* Semantic parity with `@mastra/railway` `RailwaySandbox.stop()`: the VM
+	* is released but the on-provider checkpoint survives, so a subsequent
+	* `start()` on a sandbox constructed with the same `id` can restore from
+	* it. Any in-flight capture is awaited first so the preserved checkpoint
+	* reflects the latest disk state we asked for.
+	*
+	* Corresponds to `DELETE /v1/projects/:pid/sandbox/:sandboxId` on
+	* workspace-proxy, which by contract does not touch the checkpoint. Use
+	* {@link destroy} when you want the checkpoint released too.
+	*/
 	async stop() {
-		await this.destroy();
+		if (this._captureInFlight) await this._captureInFlight.catch((error) => {
+			this.logger.warn(`stop(): failed to flush in-flight capture before teardown:`, error);
+		});
+		await this._teardownSandbox();
 	}
+	/**
+	* Destroy the sandbox **and release its recovery checkpoint**.
+	*
+	* Semantic parity with `@mastra/railway` `RailwaySandbox.destroy()`:
+	* cancels any in-flight capture (the checkpoint is about to be deleted
+	* — no reason to burn a capture on state we're releasing), asks the
+	* proxy to delete the checkpoint, then releases the VM. Both remote
+	* operations are best-effort logged failures — a stray checkpoint or a
+	* transient proxy error must not leave the caller with a half-torn-down
+	* sandbox they can't safely retry.
+	*
+	* Requires the caller to have constructed with a recovery `id` (there is
+	* no checkpoint to delete otherwise); callers without one skip the
+	* checkpoint DELETE and behave identically to {@link stop}.
+	*/
 	async destroy() {
 		if (!this._sandboxId) return;
 		const destroyedSandboxId = this._sandboxId;
+		this._captureInFlight = null;
+		if (this._hasRecoveryKey) try {
+			await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}/checkpoint`, {
+				method: "DELETE",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ id: this.id })
+			});
+		} catch (error) {
+			if (error instanceof PlatformApiError && (error.status === 404 || error.status === 410)) this.logger.debug(`destroy(): checkpoint already absent upstream (status=${error.status})`);
+			else this.logger.warn(`destroy(): failed to delete checkpoint upstream:`, error);
+		}
+		await this._teardownSandbox();
+	}
+	/**
+	* Release the remote sandbox VM and clear the local state pointing at it.
+	*
+	* Shared body of {@link stop} and {@link destroy} — both funnel through
+	* here after they've dealt with the checkpoint (preserve vs release).
+	* The VM DELETE is safe to issue in either mode: the proxy's DELETE
+	* route does not touch the checkpoint on its own, so `stop()` correctly
+	* leaves the checkpoint intact and `destroy()` has already removed it
+	* before this call.
+	*/
+	async _teardownSandbox() {
+		if (!this._sandboxId) return;
+		const destroyedSandboxId = this._sandboxId;
+		this._probeGeneration++;
 		await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
 		this._sandboxId = void 0;
 		this._createdAt = null;
 		this._lease = null;
 		this._addressRegistry?.delete(destroyedSandboxId);
 	}
+	/** Persist the configured recovery checkpoint when available. */
+	async snapshot() {
+		await this.captureCheckpoint();
+	}
+	/**
+	* Capture the sandbox's checkpoint on demand, outside any refresh timer the
+	* workspace-proxy owns internally.
+	*
+	* Intended for callers (e.g. a factory-side scheduler) that want to refresh
+	* the recovery checkpoint at semantic moments — turn end, session-idle,
+	* pre-teardown — rather than only just before the upstream's idle destroy.
+	*
+	* Mirrors the OSS `@mastra/railway` `RailwaySandbox.captureCheckpoint()`
+	* shape so factory can call `sandbox.captureCheckpoint()` uniformly and
+	* branch on `status`/`reason` without knowing which provider is underneath.
+	* Both `captured` and `coalesced` carry the checkpoint name inline so the
+	* caller can persist a session→checkpoint binding atomically with the
+	* awaited capture.
+	*
+	* Skip semantics:
+	*  - No caller-supplied `id`: returns `{ status: 'skipped', reason:
+	*    'no-checkpoint-name-configured' }`. An auto-generated random id is
+	*    never a meaningful recovery key (no future boot would look for a
+	*    checkpoint under it), so capturing would silently produce dead data.
+	*  - Not started (no `_sandboxId`): returns `{ status: 'skipped', reason:
+	*    'sandbox-not-running' }` without a round-trip.
+	*  - Upstream 410 (workspace-proxy or Railway reports the sandbox is
+	*    already destroyed): returns the same `sandbox-not-running` skip so
+	*    the discriminant matches the pre-flight case. Local state
+	*    (`_sandboxId`, `_lease`, sidecar address) is cleared as a side
+	*    effect so the next `start()` provisions fresh instead of reattaching
+	*    to a dead id. The diagnostic distinction (pre-flight vs post-hoc)
+	*    is preserved in log level: debug for the expected pre-flight skip,
+	*    warn for the surprise upstream destroy.
+	*
+	* Concurrent callers on the same instance coalesce onto a single in-flight
+	* `POST /checkpoint` so N simultaneous turn-end fires (e.g. several tabs)
+	* do not each round-trip the proxy. Both the originator and joiners
+	* receive `{ status: 'coalesced', ... }` for the joined result — the
+	* outer contract does not distinguish who started the request, only that
+	* one upstream capture was made.
+	*
+	* Never throws for expected outcomes. Transport failures (5xx, 4xx other
+	* than 410) propagate as {@link PlatformApiError}; a 410 is normalized
+	* to a skip as described above.
+	*/
+	async captureCheckpoint() {
+		if (!this._hasRecoveryKey) {
+			this.logger.debug(`captureCheckpoint skipped: no recovery key configured for sandbox ${this._sandboxId ?? "(unstarted)"}`);
+			return {
+				status: "skipped",
+				reason: "no-checkpoint-name-configured"
+			};
+		}
+		if (!this._sandboxId) {
+			this.logger.debug(`captureCheckpoint skipped: sandbox not running (local pre-flight, id=${this.id})`);
+			return {
+				status: "skipped",
+				reason: "sandbox-not-running"
+			};
+		}
+		if (this._captureInFlight) return this._captureInFlight;
+		const sandboxId = this._sandboxId;
+		const capture = this._doCaptureCheckpoint(sandboxId).finally(() => {
+			if (this._captureInFlight === capture) this._captureInFlight = null;
+		});
+		this._captureInFlight = capture;
+		return capture;
+	}
+	/**
+	* The single `POST /checkpoint` attempt behind {@link captureCheckpoint}.
+	*
+	* Split out so the coalescing wrapper can install a shared in-flight
+	* promise without inlining the transport + response-mapping logic.
+	* Joined callers observe `{ status: 'coalesced', ... }` — the initiator
+	* sees the underlying `captured` / `coalesced` / `skipped` result the
+	* proxy returned. Both are legitimate: the OSS mirror uses the same
+	* "initiator sees the truth, joiners see coalesced" split.
+	*/
+	async _doCaptureCheckpoint(sandboxId) {
+		let response;
+		try {
+			response = await this._client.request(`/sandbox/${encodeURIComponent(sandboxId)}/checkpoint`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ id: this.id })
+			});
+		} catch (error) {
+			if (error instanceof PlatformApiError && error.status === 410) {
+				this.logger.warn(`captureCheckpoint skipped: sandbox destroyed upstream (proxy 410, sandboxId=${sandboxId})`);
+				this._clearDestroyedState(sandboxId);
+				return {
+					status: "skipped",
+					reason: "sandbox-not-running"
+				};
+			}
+			throw error;
+		}
+		const json = await response.json();
+		if (json.status === "skipped") {
+			this.logger.warn(`captureCheckpoint skipped: sandbox destroyed upstream (proxy reported skipped, sandboxId=${sandboxId})`);
+			this._clearDestroyedState(sandboxId);
+			return {
+				status: "skipped",
+				reason: "sandbox-not-running"
+			};
+		}
+		return {
+			status: json.status,
+			checkpointName: json.checkpointName
+		};
+	}
+	/**
+	* Clear local state that would otherwise let the caller keep exec'ing
+	* against a sandbox the upstream has already destroyed. Mirrors what
+	* `destroy()` does minus the outbound DELETE — the sandbox is already
+	* gone, so all that remains is to stop pointing at it.
+	*
+	* Also resets `status` to `'pending'` so a subsequent `_start()` on this
+	* reused instance re-runs provisioning instead of short-circuiting on
+	* the cached `'running'` state (see `MastraSandbox._start`).
+	*/
+	_clearDestroyedState(destroyedSandboxId) {
+		this._sandboxId = void 0;
+		this._createdAt = null;
+		this._lease = null;
+		this._addressRegistry?.delete(destroyedSandboxId);
+		this.status = "pending";
+	}
 	/**
 	* Execute a command on the remote sandbox.
 	*
@@ -1006,6 +1379,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		const started = Date.now();
 		const fullCommand = buildCommand(command, args);
 		const effectiveTimeout = options?.timeout ?? this._timeout;
+		await this._awaitTransportReady();
 		const instanceUrl = this._addressRegistry?.get(this._sandboxId);
 		if (instanceUrl) {
 			const privateNet = await this._tryExecViaPrivateNetwork(instanceUrl, fullCommand, effectiveTimeout, options);