@mastra/factory 0.8.0-alpha.14 → 0.8.0-alpha.16

package/dist/workspace.d.ts

@@ -1,3 +1,4 @@
+import { SandboxFilesystem } from '@mastra/code-sdk/agents/sandbox-filesystem';
 import { getDynamicWorkspace } from '@mastra/code-sdk/agents/workspace';
 import { LocalSandbox, Workspace } from '@mastra/core/workspace';
 import type { MastraFactorySandboxConfig } from './factory.js';
@@ -5,6 +6,34 @@ import type { GithubIntegration } from './integrations/github/integration.js';
 import type { SandboxFleet } from './sandbox/fleet.js';
 import type { WorkItemsStorage } from './storage/domains/work-items/base.js';
 export declare function checkpointNameForSession(sessionId: string): string;
+/**
+ * Whether a command failure means the sandbox itself is gone (destroyed by
+ * idle GC or provider teardown) AND the command provably never started, so
+ * reviving the sandbox and replaying the command cannot run a side effect
+ * twice. Matched by error name so any provider's equivalent error classes
+ * participate without a package dependency.
+ *
+ * `SandboxExecTransportError` means both WebSocket attempts closed without an
+ * exit frame against a live sandbox. It only proves the command never started
+ * when the transport never opened (`opened: false` — the upgrade was refused
+ * outright). When the transport opened, the command may have run and mutated
+ * state before the result was lost, so replaying `git commit`, uploads, or
+ * arbitrary shell commands could execute the side effect twice; those errors
+ * surface to the caller instead.
+ */
+export declare function isDeadSandboxError(error: unknown): boolean;
+/**
+ * The local-provider equivalent of {@link isDeadSandboxError}: a local sandbox
+ * is just a directory, so it "dies" when that directory is removed — which
+ * session retirement does while an in-flight run still holds the handle.
+ *
+ * Node surfaces a missing `cwd` as ENOENT against the binary it tried to spawn
+ * (`spawn /bin/sh ENOENT`), which is textually identical to the shell itself
+ * being absent, and is also what a genuinely missing command reports. Probing
+ * the working directory is what separates "the sandbox is gone" from "that
+ * command does not exist", so only the former triggers a rebuild.
+ */
+export declare function isMissingWorkdirError(error: unknown, workdir: string | undefined): boolean;
 export declare const FACTORY_SKILLS_SOURCE_PATH: string;
 export declare const FACTORY_SKILL_NAMES: Set<string>;
 type DynamicWorkspaceContext = Parameters<typeof getDynamicWorkspace>[0];
@@ -30,7 +59,7 @@ export declare class FactoryWorkspaceRegistry {
     register(sessionId: string, workspaceId: string, generation: number, unregister: WorkspaceUnregister): Promise<boolean>;
     invalidateSession(sessionId: string): Promise<void>;
 }
-export declare function createWorkspaceFactory(options?: CreateWorkspaceFactoryOptions): ({ requestContext, mastra, skillExtension }: DynamicWorkspaceContext) => Promise<Workspace<import("@mastra/core/workspace").WorkspaceFilesystem | undefined, import("@mastra/core/workspace").WorkspaceSandbox | undefined, undefined> | Workspace<import("@mastra/core/workspace").LocalFilesystem, LocalSandbox, undefined> | undefined>;
-export declare const getFactoryWorkspace: ({ requestContext, mastra, skillExtension }: DynamicWorkspaceContext) => Promise<Workspace<import("@mastra/core/workspace").WorkspaceFilesystem | undefined, import("@mastra/core/workspace").WorkspaceSandbox | undefined, undefined> | Workspace<import("@mastra/core/workspace").LocalFilesystem, LocalSandbox, undefined> | undefined>;
+export declare function createWorkspaceFactory(options?: CreateWorkspaceFactoryOptions): ({ requestContext, mastra, skillExtension }: DynamicWorkspaceContext) => Promise<Workspace<import("@mastra/core/workspace").WorkspaceFilesystem | undefined, import("@mastra/core/workspace").WorkspaceSandbox | undefined, undefined> | Workspace<import("@mastra/core/workspace").LocalFilesystem, LocalSandbox, undefined> | Workspace<SandboxFilesystem, import("@mastra/core/workspace").WorkspaceSandbox, undefined> | undefined>;
+export declare const getFactoryWorkspace: ({ requestContext, mastra, skillExtension }: DynamicWorkspaceContext) => Promise<Workspace<import("@mastra/core/workspace").WorkspaceFilesystem | undefined, import("@mastra/core/workspace").WorkspaceSandbox | undefined, undefined> | Workspace<import("@mastra/core/workspace").LocalFilesystem, LocalSandbox, undefined> | Workspace<SandboxFilesystem, import("@mastra/core/workspace").WorkspaceSandbox, undefined> | undefined>;
 export {};
 //# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAKxE,OAAO,EAAE,YAAY,EAAoB,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAc9E,OAAO,KAAK,EAAuB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAK7E,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AAID,eAAO,MAAM,0BAA0B,QAUS,CAAC;AAEjD,eAAO,MAAM,mBAAmB,aAO9B,CAAC;AA+DH,KAAK,uBAAuB,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzE,MAAM,WAAW,6BAA6B;IAC5C,wEAAwE;IACxE,OAAO,CAAC,EAAE,0BAA0B,CAAC;IACrC,gFAAgF;IAChF,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;iEAE6D;IAC7D,SAAS,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,yBAAyB,CAAC,CAAC;IAC9D,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C;AAED,KAAK,mBAAmB,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEtD,gFAAgF;AAChF,qBAAa,wBAAwB;;IAInC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAI/B,QAAQ,CACZ,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,mBAAmB,GAC9B,OAAO,CAAC,OAAO,CAAC;IAWb,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAS1D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,6BAAkC,IAkBlE,4CAA4C,uBAAuB,uQA4XlF;AAED,eAAO,MAAM,mBAAmB,+CA9X4B,uBAAuB,sQA8XxB,CAAC"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AAE/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAKxE,OAAO,EAAE,YAAY,EAAoB,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAgB9E,OAAO,KAAK,EAAuB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAK7E,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAO1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAI1F;AAID,eAAO,MAAM,0BAA0B,QAUS,CAAC;AAEjD,eAAO,MAAM,mBAAmB,aAO9B,CAAC;AA6GH,KAAK,uBAAuB,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzE,MAAM,WAAW,6BAA6B;IAC5C,wEAAwE;IACxE,OAAO,CAAC,EAAE,0BAA0B,CAAC;IACrC,gFAAgF;IAChF,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;iEAE6D;IAC7D,SAAS,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,yBAAyB,CAAC,CAAC;IAC9D,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C;AAED,KAAK,mBAAmB,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEtD,gFAAgF;AAChF,qBAAa,wBAAwB;;IAInC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAI/B,QAAQ,CACZ,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,mBAAmB,GAC9B,OAAO,CAAC,OAAO,CAAC;IAWb,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAS1D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,6BAAkC,IA2BlE,4CAA4C,uBAAuB,oWAojBlF;AAED,eAAO,MAAM,mBAAmB,+CAtjB4B,uBAAuB,mWAsjBxB,CAAC"}

package/dist/workspace.js

@@ -1,7 +1,8 @@
 import { getFactoryAuthUserFromContext, getFactoryAuthUserId } from "./auth.js";
 import { getGithubPat } from "./integrations/github/pat.js";
 import { registerGithubPatKind, registerGithubTokenInjector } from "./integrations/github/token-refresh.js";
-import { DEFAULT_COMMAND_TIMEOUT_MS, MaterializeError, checkoutSessionBranch, materializeRepo, recycleClaimedWorkdir, runWorktreeSetup, runWorktreeTeardown } from "./integrations/github/sandbox.js";
+import { DEFAULT_COMMAND_TIMEOUT_MS, MaterializeError, checkoutSessionBranch, hasExistingCheckout, materializeRepo, recycleClaimedWorkdir, runWorktreeSetup, runWorktreeTeardown } from "./integrations/github/sandbox.js";
+import { baseCheckpointIsStale } from "./sandbox/base-checkpoint-triggers.js";
 import { getFactorySessionAddress } from "./rules/binding-context.js";
 import path, { dirname, join } from "path";
 import { LocalSandbox, LocalSkillSource, Workspace } from "@mastra/core/workspace";
@@ -17,6 +18,43 @@ const SESSION_CHECKPOINT_PREFIX = "mastracode-session";
 function checkpointNameForSession(sessionId) {
 	return `${SESSION_CHECKPOINT_PREFIX}-${sessionId}`;
 }
+/**
+* Whether a command failure means the sandbox itself is gone (destroyed by
+* idle GC or provider teardown) AND the command provably never started, so
+* reviving the sandbox and replaying the command cannot run a side effect
+* twice. Matched by error name so any provider's equivalent error classes
+* participate without a package dependency.
+*
+* `SandboxExecTransportError` means both WebSocket attempts closed without an
+* exit frame against a live sandbox. It only proves the command never started
+* when the transport never opened (`opened: false` — the upgrade was refused
+* outright). When the transport opened, the command may have run and mutated
+* state before the result was lost, so replaying `git commit`, uploads, or
+* arbitrary shell commands could execute the side effect twice; those errors
+* surface to the caller instead.
+*/
+function isDeadSandboxError(error) {
+	if (!(error instanceof Error)) return false;
+	if (error.name === "SandboxDestroyedError") return true;
+	if (error.name === "SandboxExecTransportError") return error.opened === false;
+	return /sandbox .*(destroyed|no longer exists|not found)/i.test(error.message);
+}
+/**
+* The local-provider equivalent of {@link isDeadSandboxError}: a local sandbox
+* is just a directory, so it "dies" when that directory is removed — which
+* session retirement does while an in-flight run still holds the handle.
+*
+* Node surfaces a missing `cwd` as ENOENT against the binary it tried to spawn
+* (`spawn /bin/sh ENOENT`), which is textually identical to the shell itself
+* being absent, and is also what a genuinely missing command reports. Probing
+* the working directory is what separates "the sandbox is gone" from "that
+* command does not exist", so only the former triggers a rebuild.
+*/
+function isMissingWorkdirError(error, workdir) {
+	if (!workdir) return false;
+	if (error?.code !== "ENOENT") return false;
+	return !existsSync(workdir);
+}
 const bundleDirectory = dirname(fileURLToPath(import.meta.url));
 const bundledFactorySkillsPath = join(bundleDirectory, "factory-skills");
 const FACTORY_SKILLS_SOURCE_PATH = [
@@ -68,6 +106,47 @@ var FactorySkillSource = class {
 		return this.fallback.realpath ? this.fallback.realpath(skillPath) : Promise.resolve(skillPath);
 	}
 };
+function skillSourceEnoent(skillPath) {
+	const error = /* @__PURE__ */ new Error(`ENOENT: no such file or directory, '${skillPath}'`);
+	error.code = "ENOENT";
+	return error;
+}
+/**
+* Sandbox-backed skill fallback that stays inert until the session sandbox is
+* actually materialized. Skill discovery runs on latency-sensitive paths (the
+* Factory start coordinator resolves the kickoff skill before the start route
+* responds); without this guard the first project-root read would hit the lazy
+* sandbox handle and force full provisioning + repo materialization. While the
+* sandbox is unmaterialized, project skill roots simply appear empty — bundled
+* Factory skills resolve from local disk via `FactorySkillSource`. Once the
+* sandbox exists, every call delegates straight through.
+*/
+var UnmaterializedAwareSkillSource = class {
+	fallback;
+	isMaterialized;
+	constructor(fallback, isMaterialized) {
+		this.fallback = fallback;
+		this.isMaterialized = isMaterialized;
+	}
+	async exists(skillPath) {
+		return this.isMaterialized() ? this.fallback.exists(skillPath) : false;
+	}
+	async stat(skillPath) {
+		if (!this.isMaterialized()) throw skillSourceEnoent(skillPath);
+		return this.fallback.stat(skillPath);
+	}
+	async readFile(skillPath) {
+		if (!this.isMaterialized()) throw skillSourceEnoent(skillPath);
+		return this.fallback.readFile(skillPath);
+	}
+	async readdir(skillPath) {
+		return this.isMaterialized() ? this.fallback.readdir(skillPath) : [];
+	}
+	realpath(skillPath) {
+		if (!this.isMaterialized()) return Promise.resolve(skillPath);
+		return this.fallback.realpath ? this.fallback.realpath(skillPath) : Promise.resolve(skillPath);
+	}
+};
 const factorySkillExtension = {
 	id: "web-factory",
 	paths: [FACTORY_SKILLS_MOUNT],
@@ -106,6 +185,8 @@ function createWorkspaceFactory(options = {}) {
 	const githubTokenInjectors = /* @__PURE__ */ new Map();
 	const githubTokenReconciliations = /* @__PURE__ */ new Map();
 	const inflightMaterializations = /* @__PURE__ */ new Map();
+	const materializedSandboxes = /* @__PURE__ */ new Map();
+	const constructedWorkspaces = /* @__PURE__ */ new Map();
 	return async ({ requestContext, mastra, skillExtension }) => {
 		const effectiveSkillExtension = skillExtension ?? factorySkillExtension;
 		const ctx = requestContext.get("controller");
@@ -129,14 +210,13 @@ function createWorkspaceFactory(options = {}) {
 			id: session.projectRepositoryId
 		});
 		if (!projectRepository) throw new Error(`Repository link ${session.projectRepositoryId} was not found`);
-		const connection = await storage.connections.get({
+		const [connection, repository] = await Promise.all([storage.connections.get({
 			orgId: session.orgId,
 			id: projectRepository.connectionId
-		});
-		const repository = await storage.repositories.get({
+		}), storage.repositories.get({
 			orgId: session.orgId,
 			id: projectRepository.repositoryId
-		});
+		})]);
 		if (!connection || !repository) throw new Error(`Repository link ${session.projectRepositoryId} is incomplete`);
 		if (!await storage.installations.get({
 			orgId: session.orgId,
@@ -144,15 +224,20 @@ function createWorkspaceFactory(options = {}) {
 		})) throw new Error(`GitHub installation ${connection.installationId} was not found`);
 		const repoFullName = repository.slug;
 		let workdir = isLocalSandbox ? fleet.computeLocalSessionWorkdir(repoFullName, session.id) : session.sandboxWorkdir ?? projectRepository.sandboxWorkdir;
-		if (ctx && workdir && ctx.getState()?.projectPath !== workdir) await ctx.setState({
-			projectPath: workdir,
-			projectName: repoFullName
-		});
+		let stateSeeded = false;
+		if (ctx && workdir && ctx.getState()?.projectPath !== workdir) {
+			await ctx.setState({
+				projectPath: workdir,
+				projectName: repoFullName
+			});
+			stateSeeded = true;
+		}
 		const binding = {
 			get sandboxId() {
 				return session.sandboxId;
 			},
 			checkpointName: checkpointNameForSession(session.id),
+			...!session.materializedAt && projectRepository.baseCheckpoint && !baseCheckpointIsStale(projectRepository) ? { seedCheckpointName: projectRepository.baseCheckpoint.name } : {},
 			setSandboxId: async (id) => {
 				await storage.sessions.setSandbox({
 					id: session.id,
@@ -246,7 +331,11 @@ function createWorkspaceFactory(options = {}) {
 						await workspace.destroy();
 						evicted = true;
 					} catch {}
-					if (evicted && githubTokenInjectors.get(workspaceId) === registered) githubTokenInjectors.delete(workspaceId);
+					if (evicted && githubTokenInjectors.get(workspaceId) === registered) {
+						githubTokenInjectors.delete(workspaceId);
+						materializedSandboxes.delete(workspaceId);
+						constructedWorkspaces.delete(workspaceId);
+					}
 				}
 				throw error;
 			}
@@ -256,12 +345,17 @@ function createWorkspaceFactory(options = {}) {
 		let existing;
 		try {
 			existing = mastra?.getWorkspaceById(workspaceId);
-			existing?.setToolsConfig(MASTRACODE_WORKSPACE_TOOLS);
 		} catch {
 			existing = void 0;
 		}
-		if (existing) return reconcileRegisteredWorkspace(existing);
-		const materialize = async () => {
+		existing ??= constructedWorkspaces.get(workspaceId);
+		if (existing) {
+			existing.setToolsConfig(MASTRACODE_WORKSPACE_TOOLS);
+			return reconcileRegisteredWorkspace(existing);
+		}
+		const retiredError = () => /* @__PURE__ */ new Error(`Factory session ${session.sessionId} was retired during workspace materialization`);
+		const materializeSandbox = async () => {
+			if (workspaceRegistry.generation(session.sessionId) !== workspaceGeneration) throw retiredError();
 			let claimedPooledSandbox = false;
 			if (!isLocalSandbox && !session.sandboxId) {
 				const pooled = await storage.sandboxPool.claim({ projectRepositoryId: session.projectRepositoryId });
@@ -284,7 +378,7 @@ function createWorkspaceFactory(options = {}) {
 				...isLocalSandbox ? { workingDirectory: workdir } : {},
 				actingUserId: userId
 			});
-			const runMaterialize = (target) => materializeRepo({
+			const runMaterialize = (target, skipPull) => materializeRepo({
 				row: {
 					id: session.id,
 					sandboxWorkdir: workdir,
@@ -296,19 +390,21 @@ function createWorkspaceFactory(options = {}) {
 				},
 				sandbox: target,
 				token,
-				storage: storage.sessions
+				storage: storage.sessions,
+				skipPullOnExistingCheckout: skipPull
 			});
 			const isGitMissing = (error) => error instanceof MaterializeError && error.code === "git-missing";
 			let sandbox = await ensureSandbox();
 			if (claimedPooledSandbox) await recycleClaimedWorkdir(sandbox, workdir, repository.defaultBranch);
+			const seededFromBaseCheckpoint = !!binding.seedCheckpointName && !session.materializedAt && !claimedPooledSandbox && await hasExistingCheckout(sandbox, workdir, repoFullName);
 			try {
-				await runMaterialize(sandbox);
+				await runMaterialize(sandbox, seededFromBaseCheckpoint);
 			} catch (error) {
 				if (!isGitMissing(error)) throw error;
 				await fleet.teardownSandbox(binding, sandbox);
 				sandbox = await ensureSandbox();
 				try {
-					await runMaterialize(sandbox);
+					await runMaterialize(sandbox, false);
 				} catch (retryError) {
 					if (isGitMissing(retryError)) await fleet.teardownSandbox(binding, sandbox);
 					throw retryError;
@@ -320,7 +416,7 @@ function createWorkspaceFactory(options = {}) {
 				token,
 				repoFullName
 			});
-			if (projectRepository.setupCommand) try {
+			if (projectRepository.setupCommand && !seededFromBaseCheckpoint) try {
 				await runWorktreeSetup(sandbox, workdir, projectRepository.setupCommand);
 			} catch (setupError) {
 				if (projectRepository.teardownCommand) try {
@@ -346,47 +442,122 @@ function createWorkspaceFactory(options = {}) {
 				generation: 0,
 				tokenReplacementPending: false
 			};
+			if (workspaceRegistry.generation(session.sessionId) !== workspaceGeneration) {
+				try {
+					await fleet.teardownSandbox(binding, sandbox);
+				} catch (teardownError) {
+					console.warn("[Mastra Factory] Sandbox teardown after mid-materialization retirement failed", {
+						orgId: session.orgId,
+						sessionId: session.sessionId,
+						error: teardownError instanceof Error ? teardownError.message.slice(-2e3) : String(teardownError)
+					});
+				}
+				throw retiredError();
+			}
 			githubTokenInjectors.set(workspaceId, tokenRegistration);
 			registerGithubTokenContext(tokenRegistration);
-			const filesystem = new SandboxFilesystem({
-				sandbox,
-				workdir
-			});
-			const projectSkillPaths = [
-				path.join(configDir, "skills"),
-				".claude/skills",
-				".agents/skills"
-			];
-			const skillPaths = [...effectiveSkillExtension?.paths ?? [], ...projectSkillPaths];
-			const workspace = new Workspace({
-				id: workspaceId,
-				name: "Mastra Code Factory Session Workspace",
-				filesystem,
-				sandbox,
-				tools: MASTRACODE_WORKSPACE_TOOLS,
-				skills: skillPaths,
-				skillSource: effectiveSkillExtension?.createSource(filesystem, projectSkillPaths) ?? filesystem
-			});
-			mastra?.addWorkspace(workspace, workspaceId, { source: "mastra" });
-			if (!await workspaceRegistry.register(session.sessionId, workspaceId, workspaceGeneration, async () => {
-				githubTokenInjectors.delete(workspaceId);
-				await mastra?.removeWorkspace?.(workspaceId);
-			})) throw new Error(`Factory session ${session.sessionId} was retired during workspace materialization`);
-			return workspace;
+			return sandbox;
 		};
-		const inflight = inflightMaterializations.get(workspaceId);
-		if (inflight) return reconcileRegisteredWorkspace(await inflight);
-		const materialization = materialize();
-		inflightMaterializations.set(workspaceId, materialization);
-		try {
-			return await materialization;
-		} finally {
-			inflightMaterializations.delete(workspaceId);
-		}
+		const ensureMaterialized = async () => {
+			const ready = materializedSandboxes.get(workspaceId);
+			if (ready) return ready;
+			let inflight = inflightMaterializations.get(workspaceId);
+			if (!inflight) {
+				inflight = materializeSandbox();
+				inflightMaterializations.set(workspaceId, inflight);
+				inflight.then((sb) => {
+					materializedSandboxes.set(workspaceId, sb);
+					workspace.skills?.refresh().catch(() => {});
+				}, () => {});
+			}
+			try {
+				return await inflight;
+			} finally {
+				if (inflightMaterializations.get(workspaceId) === inflight) inflightMaterializations.delete(workspaceId);
+			}
+		};
+		const lazySandbox = {
+			get id() {
+				return materializedSandboxes.get(workspaceId)?.id ?? workspaceId;
+			},
+			name: "Factory Lazy Sandbox",
+			get provider() {
+				return fleet.provider;
+			},
+			get status() {
+				return materializedSandboxes.has(workspaceId) ? "ready" : "pending";
+			},
+			get supportsCheckpoints() {
+				return materializedSandboxes.get(workspaceId)?.supportsCheckpoints ?? false;
+			},
+			getInstructions() {
+				return materializedSandboxes.get(workspaceId)?.getInstructions?.() ?? fleet.getInstructions();
+			},
+			clone() {
+				throw new Error("The Factory session sandbox cannot be cloned from a lazy handle.");
+			},
+			async start() {},
+			async getInfo() {
+				return (await ensureMaterialized()).getInfo();
+			},
+			async executeCommand(command, args, options) {
+				const sandbox = await ensureMaterialized();
+				try {
+					return await sandbox.executeCommand(command, args, options);
+				} catch (error) {
+					if (!isDeadSandboxError(error) && !(isLocalSandbox && isMissingWorkdirError(error, workdir))) throw error;
+					if (materializedSandboxes.get(workspaceId) === sandbox) materializedSandboxes.delete(workspaceId);
+					return (await ensureMaterialized()).executeCommand(command, args, options);
+				}
+			},
+			setEnvironmentVariable(name, value) {
+				const sandbox = materializedSandboxes.get(workspaceId);
+				if (!sandbox?.setEnvironmentVariable) throw new Error("The Factory session sandbox is not materialized yet.");
+				sandbox.setEnvironmentVariable(name, value);
+			},
+			async snapshot() {
+				await materializedSandboxes.get(workspaceId)?.snapshot?.();
+			},
+			async stop() {
+				await materializedSandboxes.get(workspaceId)?.stop?.();
+			}
+		};
+		const filesystem = new SandboxFilesystem({
+			id: `sandbox-fs:${workspaceId}:${workdir}`,
+			sandbox: lazySandbox,
+			workdir
+		});
+		const projectSkillPaths = [
+			path.join(configDir, "skills"),
+			".claude/skills",
+			".agents/skills"
+		];
+		const guardedSkillFallback = new UnmaterializedAwareSkillSource(filesystem, () => materializedSandboxes.has(workspaceId));
+		const workspace = new Workspace({
+			id: workspaceId,
+			name: "Mastra Code Factory Session Workspace",
+			filesystem,
+			sandbox: lazySandbox,
+			tools: MASTRACODE_WORKSPACE_TOOLS,
+			skills: [...effectiveSkillExtension?.paths ?? [], ...projectSkillPaths],
+			skillSource: effectiveSkillExtension?.createSource(guardedSkillFallback, projectSkillPaths) ?? guardedSkillFallback
+		});
+		mastra?.addWorkspace(workspace, workspaceId, { source: "mastra" });
+		constructedWorkspaces.set(workspaceId, workspace);
+		if (!await workspaceRegistry.register(session.sessionId, workspaceId, workspaceGeneration, async () => {
+			githubTokenInjectors.delete(workspaceId);
+			materializedSandboxes.delete(workspaceId);
+			constructedWorkspaces.delete(workspaceId);
+			await mastra?.removeWorkspace?.(workspaceId);
+		})) throw new Error(`Factory session ${session.sessionId} was retired during workspace materialization`);
+		if (stateSeeded) ensureMaterialized().catch((error) => {
+			console.error(`[factory:workspace] background materialization for ${workspaceId} failed`, error);
+		});
+		return workspace;
 	};
 }
 const getFactoryWorkspace = createWorkspaceFactory();
 //#endregion
-export { FACTORY_SKILLS_SOURCE_PATH, FACTORY_SKILL_NAMES, FactoryWorkspaceRegistry, checkpointNameForSession, createWorkspaceFactory, getFactoryWorkspace };
+export { FACTORY_SKILLS_SOURCE_PATH, FACTORY_SKILL_NAMES, FactoryWorkspaceRegistry, checkpointNameForSession, createWorkspaceFactory, getFactoryWorkspace, isDeadSandboxError, isMissingWorkdirError };
 
 //# sourceMappingURL=workspace.js.map