@mastra/factory 0.21.1-alpha.2 → 0.22.0-alpha.4

package/dist/supervisor/read-tools.js

@@ -2,8 +2,8 @@ import { FACTORY_RULE_STAGES, factoryRuleStage } from "../rules/types.js";
 import { factoryDispatchFailureMetadata } from "../rules/dispatch-errors.js";
 import { decisionRetryable, overtakenDecisionIds } from "../rules/decision-applicability.js";
 import { runFactoryHealthCheck } from "./health.js";
-import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
+import { createTool } from "@mastra/core/tools";
 //#region src/supervisor/read-tools.ts
 const MAX_TEXT = 600;
 const MAX_ERROR = 400;

package/dist/supervisor/write-tools.js

@@ -3,8 +3,8 @@ import { boardForWorkItem } from "../boards/semantics.js";
 import "../boards/index.js";
 import { factoryDispatchFailureMetadata } from "../rules/dispatch-errors.js";
 import { overtakenDecisionIds } from "../rules/decision-applicability.js";
-import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
+import { createTool } from "@mastra/core/tools";
 //#region src/supervisor/write-tools.ts
 function createFactorySupervisorWriteTools(deps) {
 	const now = deps.now ?? (() => /* @__PURE__ */ new Date());

package/dist/workspace.d.ts

@@ -1,11 +1,11 @@
 import { SandboxFilesystem } from '@mastra/code-sdk/agents/sandbox-filesystem';
 import type { getDynamicWorkspace } from '@mastra/code-sdk/agents/workspace';
 import { Workspace } from '@mastra/core/workspace';
-import type { SkillSource, SkillSourceEntry, SkillSourceStat, WorkspaceSandbox } from '@mastra/core/workspace';
-import type { VersionControl } from './capabilities/version-control.js';
-import type { MastraFactorySandboxConfig } from './factory.js';
+import type { FactorySandbox, SkillSource, SkillSourceEntry, SkillSourceStat, WorkspaceSandbox } from '@mastra/core/workspace';
+import type { RepositoryAccess, VersionControl } from './capabilities/version-control.js';
 import type { GithubIntegration } from './integrations/github/integration.js';
-import type { FactoryProjectsStorage } from './storage/domains/projects/base.js';
+import type { FactorySandboxContext } from './sandbox/session-sandbox.js';
+import type { FactoryProject, FactoryProjectsStorage } from './storage/domains/projects/base.js';
 import type { SourceControlStorageHandle } from './storage/domains/source-control/base.js';
 import type { WorkItemsStorage } from './storage/domains/work-items/base.js';
 export declare const BUNDLED_FACTORY_SKILLS_PATH: string;
@@ -51,15 +51,15 @@ export interface WorkspaceSourceControlProvider {
     /** Stable integration id used to select the provider-owned storage partition. */
     id: string;
     /** Provider capability used to resolve fresh repository credentials. */
-    versionControl: Pick<VersionControl, 'getRepositoryAccess'>;
+    versionControl: Pick<VersionControl, 'getRepositoryAccess' | 'getRepositoriesAccess'>;
     /** Provider-owned source-control rows, including Factory sessions. */
     storage: SourceControlStorageHandle;
     /** Present only for GitHub, whose CLI PAT rotation has additional semantics. */
     github?: GithubIntegration;
 }
 export interface CreateWorkspaceFactoryOptions {
-    /** Factory sandbox runtime config (session sandbox callback). */
-    sandbox?: MastraFactorySandboxConfig;
+    /** The normalized factory sandbox constructing one sandbox per session. */
+    sandbox?: FactorySandbox;
     /** Defaults to `'lazy'`. */
     sandboxStart?: FactorySandboxStart;
     /** Source-control providers whose repositories may back Factory sessions. */
@@ -83,6 +83,49 @@ export declare class FactoryWorkspaceRegistry {
     register(sessionId: string, workspaceId: string, generation: number, unregister: WorkspaceUnregister): Promise<boolean>;
     invalidateSession(sessionId: string): Promise<void>;
 }
+/** One environment repository as the sandbox context and the boot need it, in position order. */
+export interface SessionEnvironmentRepo {
+    projectRepositoryId: string;
+    repositoryId: string;
+    slug: string;
+    /** The session's base branch: the link's branch when set, else the repository default. */
+    defaultBranch: string;
+    /** The repository's own default branch, which the template image clones and pins. */
+    templateBranch: string;
+    position: number;
+    setupCommand: string | undefined;
+    teardownCommand: string | undefined;
+}
+/** The session's factory environment, resolved from the project and its `inEnvironment` links. */
+export interface SessionEnvironment {
+    repos: SessionEnvironmentRepo[];
+    workspaceSetupCommand: string | undefined;
+    /** Only an absolute root is passed on; the templates reject anything else. */
+    workingDirectory: string | undefined;
+    /** The project's stored provider settings document, `{}` when nothing was set. */
+    settings: Record<string, unknown>;
+}
+/**
+ * The project's environment as a session (or an environment build) sees it:
+ * every `inEnvironment` link under this source-control integration in
+ * position order, plus the project's settings, setup command and workdir.
+ */
+export declare function resolveProjectEnvironment(storage: Pick<SourceControlStorageHandle, 'projectRepositories' | 'repositories'>, project: FactoryProject): Promise<SessionEnvironment>;
+/**
+ * The context fields the list form of the repo templates needs: one entry per
+ * environment repository, each minting its own token at build time, with
+ * `getRepositoryAccess` present but undefined (the two are mutually exclusive
+ * for the template). Shared by session boot and environment builds so both
+ * resolve the same template identity; `resolveHead` is only set when given.
+ */
+export declare function environmentSandboxContext(environment: SessionEnvironment, options: {
+    orgId: string;
+    getRepositoryAccess: (args: {
+        orgId: string;
+        repositoryId: string;
+    }) => Promise<RepositoryAccess>;
+    resolveHead?: FactorySandboxContext['resolveHead'];
+}): Omit<FactorySandboxContext, 'sessionId'>;
 export declare function createWorkspaceFactory(options?: CreateWorkspaceFactoryOptions): ({ requestContext, mastra, skillExtension }: DynamicWorkspaceContext) => Promise<Workspace<import("@mastra/core/workspace").WorkspaceFilesystem | undefined, WorkspaceSandbox | undefined, undefined> | Workspace<SandboxFilesystem, 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":"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"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}

package/dist/workspace.js

@@ -1,17 +1,20 @@
 import { timedPhase } from "./timing.js";
 import { getFactoryAuthOrgId, getFactoryAuthUserFromContext, getFactoryAuthUserId } from "./auth.js";
 import { mergeRequestNumberFromBranch, pullRequestNumberFromBranch } from "./work-item-branch.js";
+import { redactCredentials } from "./environment/build.js";
 import { getGithubPat } from "./integrations/github/pat.js";
+import { DEFAULT_COMMAND_TIMEOUT_MS, SetupCommandError, checkoutSessionBranch, materializeRepo, runSetupCommand, runTeardownCommand, syncEnvironmentRepository } from "./integrations/github/sandbox.js";
 import { registerGithubPatKind, registerGithubRefreshTarget, registerGithubTokenInjector, registerGithubTokenInjectorResolver } from "./integrations/github/token-refresh.js";
 import { requireExec } from "./sandbox/materialization.js";
-import { createSessionSetupHook, evictSessionSandbox, getSessionSandbox, hasFailedSetupCommand, recordFailedSetupCommand, resolveSessionWorkdir } from "./sandbox/session-sandbox.js";
-import { DEFAULT_COMMAND_TIMEOUT_MS, SetupCommandError, checkoutSessionBranch, materializeRepo, runSetupCommand, runTeardownCommand } from "./integrations/github/sandbox.js";
+import { repositoryDirectoryName } from "./sandbox/workdir.js";
+import { createEnvironmentSetupHook, createSessionSetupHook, evictSessionSandbox, getSessionSandbox, hasFailedSetupCommand, recordFailedSetupCommand, resolveSessionWorkdir } from "./sandbox/session-sandbox.js";
+import { clearSessionEnvironment, recordSessionEnvironment, setSessionEnvironmentNote } from "./session/environment-state-processor.js";
 import { parseSupervisorResourceId } from "./supervisor/session.js";
-import path, { dirname, join } from "path";
 import { LocalSkillSource, Workspace } from "@mastra/core/workspace";
-import { SandboxFilesystem } from "@mastra/code-sdk/agents/sandbox-filesystem";
 import { existsSync } from "fs";
+import path, { dirname, join } from "path";
 import { fileURLToPath } from "url";
+import { SandboxFilesystem } from "@mastra/code-sdk/agents/sandbox-filesystem";
 import { MASTRACODE_WORKSPACE_TOOLS } from "@mastra/code-sdk/agents/tool-availability";
 import { DEFAULT_CONFIG_DIR } from "@mastra/code-sdk/constants";
 //#region src/workspace.ts
@@ -241,6 +244,106 @@ async function resolveSourceControlSession(providers, sessionId) {
 	if (matches.length > 1) throw new Error(`Factory session ${sessionId} is ambiguous across source-control providers`);
 	return matches[0] ?? null;
 }
+/**
+* Resolve the factory environment a session boots from: the project's
+* settings plus every `inEnvironment` link of the project under this
+* source-control integration, ordered by position. `undefined` when the
+* session carries no factory or the project is gone. With no link in the
+* environment `repos` is empty and the session keeps the single-repository
+* sandbox of its own link, still booted with the project's settings. A link
+* whose repository row is missing is skipped with a warning rather than
+* failing every start of the session.
+*/
+async function resolveSessionEnvironment(projects, storage, session) {
+	if (!projects || !session.factoryProjectId) return void 0;
+	const project = await projects.get({
+		orgId: session.orgId,
+		id: session.factoryProjectId
+	});
+	if (!project) return void 0;
+	return resolveProjectEnvironment(storage, project);
+}
+/**
+* The project's environment as a session (or an environment build) sees it:
+* every `inEnvironment` link under this source-control integration in
+* position order, plus the project's settings, setup command and workdir.
+*/
+async function resolveProjectEnvironment(storage, project) {
+	const orgId = project.orgId;
+	const links = (await storage.projectRepositories.listByProject({
+		orgId,
+		factoryProjectId: project.id
+	})).filter((link) => link.inEnvironment).sort((a, b) => a.position - b.position || a.createdAt.getTime() - b.createdAt.getTime());
+	const repos = [];
+	const directories = /* @__PURE__ */ new Set();
+	for (const link of links) {
+		const repository = await storage.repositories.get({
+			orgId,
+			id: link.repositoryId
+		});
+		if (!repository) {
+			console.warn("[Mastra Factory] Environment repository link has no repository row; skipping it", {
+				orgId,
+				factoryProjectId: project.id,
+				projectRepositoryId: link.id
+			});
+			continue;
+		}
+		const directory = repositoryDirectoryName(repository.slug);
+		if (directories.has(directory)) {
+			console.warn("[Mastra Factory] Environment repository shares its directory name with an earlier one; skipping it", {
+				orgId,
+				factoryProjectId: project.id,
+				projectRepositoryId: link.id,
+				slug: repository.slug,
+				directory
+			});
+			continue;
+		}
+		directories.add(directory);
+		repos.push({
+			projectRepositoryId: link.id,
+			repositoryId: repository.id,
+			slug: repository.slug,
+			defaultBranch: link.branch || repository.defaultBranch,
+			templateBranch: repository.defaultBranch,
+			position: link.position,
+			setupCommand: link.setupCommand ?? void 0,
+			teardownCommand: link.teardownCommand ?? void 0
+		});
+	}
+	const workdir = project.sandboxWorkingDirectory?.trim();
+	return {
+		repos,
+		workspaceSetupCommand: project.workspaceSetupCommand?.trim() || void 0,
+		workingDirectory: workdir?.startsWith("/") ? workdir : void 0,
+		settings: project.sandboxSettings ?? {}
+	};
+}
+/**
+* The context fields the list form of the repo templates needs: one entry per
+* environment repository, each minting its own token at build time, with
+* `getRepositoryAccess` present but undefined (the two are mutually exclusive
+* for the template). Shared by session boot and environment builds so both
+* resolve the same template identity; `resolveHead` is only set when given.
+*/
+function environmentSandboxContext(environment, options) {
+	return {
+		setupCommand: void 0,
+		getRepositoryAccess: void 0,
+		repos: environment.repos.map((repo) => ({
+			getRepositoryAccess: () => options.getRepositoryAccess({
+				orgId: options.orgId,
+				repositoryId: repo.repositoryId
+			}),
+			...repo.setupCommand ? { setupCommand: repo.setupCommand } : {}
+		})),
+		...environment.workspaceSetupCommand ? { workspaceSetupCommand: environment.workspaceSetupCommand } : {},
+		continueOnSetupFailure: true,
+		...environment.workingDirectory ? { workingDirectory: environment.workingDirectory } : {},
+		...options.resolveHead ? { resolveHead: options.resolveHead } : {}
+	};
+}
 function createWorkspaceFactory(options = {}) {
 	const { sandbox: sandboxConfig, github, projects, workItems } = options;
 	const sourceControls = options.sourceControls ?? (github ? [{
@@ -276,14 +379,14 @@ function createWorkspaceFactory(options = {}) {
 		const userId = getFactoryAuthUserId(user);
 		if (!user?.organizationId || !userId) throw new Error(`Factory session ${session.sessionId} was resolved without a caller identity`);
 		if (user.organizationId !== session.orgId || session.visibility === "private" && userId !== session.userId) throw new Error(`Factory session ${session.sessionId} is not available to the current user`);
-		if (!sandboxConfig) throw new Error("A sandbox callback is required to create a Factory session workspace");
-		const createSessionSandboxInstance = sandboxConfig;
+		if (!sandboxConfig) throw new Error("A sandbox is required to create a Factory session workspace");
+		const factorySandbox = sandboxConfig;
 		const githubProvider = sourceControl.github;
 		const storage = sourceControl.storage;
-		const projectRepository = await storage.projectRepositories.get({
+		const projectRepository = session.projectRepositoryId ? await storage.projectRepositories.get({
 			orgId: session.orgId,
 			id: session.projectRepositoryId
-		});
+		}) : null;
 		if (!projectRepository) throw new Error(`Repository link ${session.projectRepositoryId} was not found`);
 		const [connection, repository] = await Promise.all([storage.connections.get({
 			orgId: session.orgId,
@@ -298,12 +401,24 @@ function createWorkspaceFactory(options = {}) {
 			id: connection.installationId
 		})) throw new Error(`${sourceControl.id} installation ${connection.installationId} was not found`);
 		const repoFullName = repository.slug;
+		const resolvedEnvironment = await resolveSessionEnvironment(projects, storage, session);
+		const sandboxSettings = resolvedEnvironment?.settings ?? {};
+		const environment = resolvedEnvironment?.repos.some((repo) => repo.projectRepositoryId === projectRepository.id) ? resolvedEnvironment : void 0;
+		const tokenRepositoryIds = environment ? [repository.id, ...environment.repos.map((repo) => repo.repositoryId).filter((id) => id !== repository.id)] : [repository.id];
 		if (githubProvider) registerGithubRefreshTarget(requestContext, {
 			orgId: session.orgId,
-			repositoryId: repository.id
+			repositoryId: repository.id,
+			...tokenRepositoryIds.length > 1 ? { mint: () => getRepositoryToken() } : {}
 		});
 		const runSetupOn = (target, workdir, gate) => runSessionSetup(requireExec(target), workdir, gate);
-		const guardedSetup = createSessionSetupHook(runSetupOn, session.id, repoFullName, projectRepository.setupCommand ?? void 0);
+		const runEnvironmentSetupOn = (target, gate) => runSessionEnvironmentSetup(requireExec(target), gate);
+		const guardedSetup = environment ? createEnvironmentSetupHook(runEnvironmentSetupOn, session.id, repoFullName, {
+			repos: environment.repos.map((repo) => ({
+				slug: repo.slug,
+				...repo.setupCommand ? { setupCommand: repo.setupCommand } : {}
+			})),
+			...environment.workspaceSetupCommand ? { workspaceSetupCommand: environment.workspaceSetupCommand } : {}
+		}) : createSessionSetupHook(runSetupOn, session.id, repoFullName, projectRepository.setupCommand ?? void 0);
 		const setupHook = async (args) => {
 			if (workspaceRegistry.generation(session.sessionId) !== workspaceGeneration) throw retiredError();
 			let setupError;
@@ -319,7 +434,7 @@ function createWorkspaceFactory(options = {}) {
 				await storage.sessions.setSandbox({
 					id: session.id,
 					sandboxId: target.sandboxId ?? null,
-					sandboxWorkdir: sessionEntry.workdir ?? ""
+					sandboxWorkdir: sessionWorkdir(sessionEntry.workdir) ?? ""
 				});
 				constructedWorkspaces.get(workspaceId)?.skills?.refresh().catch(() => {});
 			};
@@ -370,16 +485,21 @@ function createWorkspaceFactory(options = {}) {
 			await finishStart();
 		};
 		const constructSessionEntry = () => getSessionSandbox(session.id, repoFullName, () => {
-			const sandbox = createSessionSandboxInstance({
+			const sandbox = factorySandbox.create({
 				sessionId: session.id,
 				sandboxId: session.sandboxId ?? void 0,
 				repoFullName,
-				setupCommand: projectRepository.setupCommand ?? void 0,
-				getRepositoryAccess: () => sourceControl.versionControl.getRepositoryAccess({
+				...environment ? environmentSandboxContext(environment, {
 					orgId: session.orgId,
-					repositoryId: repository.id
-				})
-			});
+					getRepositoryAccess: (args) => sourceControl.versionControl.getRepositoryAccess(args)
+				}) : {
+					setupCommand: projectRepository.setupCommand ?? void 0,
+					getRepositoryAccess: () => sourceControl.versionControl.getRepositoryAccess({
+						orgId: session.orgId,
+						repositoryId: repository.id
+					})
+				}
+			}, sandboxSettings);
 			sandbox.setOnStart((previous) => async (args) => {
 				await timedPhase(`workspace.onStart(${args.outcome})`, async () => {
 					await setupHook(args);
@@ -388,7 +508,7 @@ function createWorkspaceFactory(options = {}) {
 			});
 			startEagerly = eagerSandboxStart;
 			return sandbox;
-		});
+		}, environment?.repos.map((repo) => repo.slug) ?? []);
 		let startEagerly = false;
 		const fireEagerStart = () => {
 			if (!startEagerly) return;
@@ -398,11 +518,15 @@ function createWorkspaceFactory(options = {}) {
 			});
 		};
 		const sessionEntry = constructSessionEntry();
-		const workdir = sessionEntry.workdir;
+		const multiRepo = (environment?.repos.length ?? 0) > 1;
+		const sessionWorkdir = (checkout) => checkout === void 0 ? void 0 : multiRepo ? path.posix.dirname(checkout) : checkout;
+		const workdir = sessionWorkdir(sessionEntry.workdir);
 		sessionEntry.sandbox.provider;
-		if (ctx && workdir && ctx.getState()?.projectPath !== workdir) await ctx.setState({
+		const checkoutDirs = environment && multiRepo ? [repositoryDirectoryName(repoFullName), ...environment.repos.filter((repo) => repo.slug.toLowerCase() !== repoFullName.toLowerCase()).map((repo) => repositoryDirectoryName(repo.slug))] : void 0;
+		if (ctx && workdir && (ctx.getState()?.projectPath !== workdir || ctx.getState()?.instructionRoots?.join("\n") !== checkoutDirs?.join("\n"))) await ctx.setState({
 			projectPath: workdir,
-			projectName: repoFullName
+			projectName: repoFullName,
+			instructionRoots: checkoutDirs
 		});
 		const findSessionBinding = async () => {
 			const binding = await workItems.findActiveRunBindingForSession({
@@ -431,7 +555,34 @@ function createWorkspaceFactory(options = {}) {
 			orgId: session.orgId,
 			repositoryId: repository.id
 		});
+		let tokenScopeWarned = false;
 		const getRepositoryToken = async () => {
+			if (tokenRepositoryIds.length > 1) {
+				let reason = "provider mints per-repository tokens only";
+				let wide;
+				if (sourceControl.versionControl.getRepositoriesAccess) try {
+					wide = await sourceControl.versionControl.getRepositoriesAccess({
+						orgId: session.orgId,
+						repositoryIds: tokenRepositoryIds
+					});
+					reason = "provider cannot mint one token for this repository set";
+				} catch (error) {
+					reason = `provider failed to mint one token for this repository set (${error instanceof Error ? error.name : "error"})`;
+				}
+				if (wide?.authorization?.token) {
+					setSessionEnvironmentNote(session.sessionId, null);
+					return wide.authorization.token;
+				}
+				if (!tokenScopeWarned) {
+					tokenScopeWarned = true;
+					console.warn("[Mastra Factory] GH_TOKEN covers the session repository only", {
+						sessionId: session.sessionId,
+						repositories: environment?.repos.map((repo) => repo.slug) ?? [repoFullName],
+						reason
+					});
+				}
+				setSessionEnvironmentNote(session.sessionId, `GH_TOKEN covers ${repoFullName} only; use the source_control_* tools for other repositories.`);
+			}
 			const token = (await getRepositoryAccess()).authorization?.token;
 			if (!token) throw new Error("Repository access did not include a bearer token for the Factory session");
 			return token;
@@ -634,17 +785,185 @@ function createWorkspaceFactory(options = {}) {
 				}
 			}
 		};
+		const runSessionEnvironmentSetup = async (target, gate) => {
+			const repos = environment.repos;
+			const primaryDir = `${gate.root}/${repositoryDirectoryName(repoFullName)}`;
+			const states = [];
+			const failures = /* @__PURE__ */ new Map();
+			const repeated = /* @__PURE__ */ new Set();
+			let primaryError;
+			const record = () => {
+				if (workspaceRegistry.generation(session.sessionId) !== workspaceGeneration) return;
+				recordSessionEnvironment(session.sessionId, {
+					workingDirectory: gate.root,
+					repositories: states
+				}, states.flatMap((state) => {
+					const command = repos.find((repo) => repo.slug === state.slug)?.teardownCommand;
+					return command ? [{
+						slug: state.slug,
+						dir: state.dir,
+						command
+					}] : [];
+				}));
+			};
+			let inFlight;
+			try {
+				for (const repo of repos) {
+					inFlight = repo.slug;
+					const entry = gate.repos.find((candidate) => candidate.slug === repo.slug);
+					if (!entry) continue;
+					const isPrimary = repo.projectRepositoryId === session.projectRepositoryId;
+					const state = {
+						slug: repo.slug,
+						dir: entry.dir,
+						branch: null,
+						defaultBranch: repo.defaultBranch,
+						position: repo.position,
+						setupStatus: repo.setupCommand ? "ok" : "skipped"
+					};
+					states.push(state);
+					if (isPrimary) {
+						try {
+							await runSessionSetup(target, primaryDir, entry.gate);
+							state.branch = session.branch;
+							if (repo.setupCommand && hasFailedSetupCommand(session.id, repo.setupCommand)) {
+								state.setupStatus = "failed";
+								repeated.add(repo.slug);
+							}
+						} catch (error) {
+							if (!(error instanceof SetupCommandError)) throw error;
+							state.branch = session.branch;
+							state.setupStatus = "failed";
+							failures.set(repo.slug, error.message);
+							primaryError = error;
+						}
+						continue;
+					}
+					try {
+						const access = await sourceControl.versionControl.getRepositoryAccess({
+							orgId: session.orgId,
+							repositoryId: repo.repositoryId
+						});
+						const token = access.authorization?.token;
+						if (!token) throw new Error(`Repository access for ${repo.slug} did not include a bearer token`);
+						await materializeRepo({
+							row: {
+								id: session.id,
+								sandboxWorkdir: entry.dir,
+								materializedAt: null
+							},
+							repoInfo: {
+								repoFullName: repo.slug,
+								defaultBranch: repo.defaultBranch,
+								cloneUrl: access.cloneUrl,
+								authUsername: access.authorization?.username
+							},
+							sandbox: target,
+							token,
+							storage: { markMaterialized: async () => {} }
+						});
+						state.branch = (await timedPhase(`workspace.sync(${repo.slug})`, () => syncEnvironmentRepository(target, entry.dir, {
+							branch: session.branch,
+							defaultBranch: repo.defaultBranch,
+							token,
+							repoFullName: repo.slug,
+							cloneUrl: access.cloneUrl,
+							authUsername: access.authorization?.username
+						}))).branch;
+					} catch (error) {
+						console.warn("[Mastra Factory] Environment repository could not be synced; continuing the boot", {
+							orgId: session.orgId,
+							sessionId: session.sessionId,
+							projectRepositoryId: repo.projectRepositoryId,
+							error: error instanceof Error ? error.message.slice(-2e3) : String(error)
+						});
+						state.setupStatus = "failed";
+						failures.set(repo.slug, error instanceof Error ? error.message : String(error));
+						continue;
+					}
+					if (!repo.setupCommand || entry.gate.setupDone) continue;
+					if (hasFailedSetupCommand(session.id, `${repo.slug}:${repo.setupCommand}`)) {
+						state.setupStatus = "failed";
+						repeated.add(repo.slug);
+						continue;
+					}
+					try {
+						await timedPhase(`workspace.setup(${repo.slug})`, () => runSetupCommand(target, entry.dir, repo.setupCommand));
+						await entry.gate.markSetupDone();
+					} catch (error) {
+						if (!(error instanceof SetupCommandError)) throw error;
+						recordFailedSetupCommand(session.id, `${repo.slug}:${repo.setupCommand}`);
+						state.setupStatus = "failed";
+						failures.set(repo.slug, error.message);
+						console.warn("[Mastra Factory] Environment repository setup command failed; continuing the boot", {
+							orgId: session.orgId,
+							sessionId: session.sessionId,
+							projectRepositoryId: repo.projectRepositoryId,
+							error: error.message.slice(-2e3)
+						});
+					}
+				}
+				inFlight = void 0;
+				const workspaceCommand = environment.workspaceSetupCommand;
+				if (workspaceCommand && !gate.workspace.setupDone) if (hasFailedSetupCommand(session.id, `workspace:${workspaceCommand}`)) console.warn("[Mastra Factory] Skipping workspace setup command that already failed this session", {
+					orgId: session.orgId,
+					sessionId: session.sessionId
+				});
+				else try {
+					await timedPhase("workspace.setup(workspace)", () => runSetupCommand(target, gate.root, workspaceCommand));
+					await gate.workspace.markSetupDone();
+				} catch (error) {
+					if (!(error instanceof SetupCommandError)) throw error;
+					recordFailedSetupCommand(session.id, `workspace:${workspaceCommand}`);
+					throw new SetupCommandError(`${error.message}. The sandbox stays usable: the workspace setup command is skipped for the rest of the session. Retry your command, then fix it in the environment settings or run it manually.`, error.code);
+				}
+			} finally {
+				record();
+				await recordSetupResults(repos, states, failures, inFlight, repeated);
+			}
+			if (primaryError) throw primaryError;
+		};
+		const recordSetupResults = async (repos, states, failures, inFlight, repeated) => {
+			const builtAt = /* @__PURE__ */ new Date();
+			try {
+				for (const state of states) {
+					if (state.setupStatus === "skipped") continue;
+					if (state.slug === inFlight && state.setupStatus !== "failed") continue;
+					if (repeated.has(state.slug)) continue;
+					const repo = repos.find((candidate) => candidate.slug === state.slug);
+					if (!repo) continue;
+					const error = failures.get(state.slug);
+					await storage.projectRepositories.setBuildStatus({
+						orgId: session.orgId,
+						id: repo.projectRepositoryId,
+						status: state.setupStatus === "failed" ? "failed" : "configured",
+						error: error === void 0 ? null : redactCredentials(error).slice(-2e3),
+						builtAt
+					});
+				}
+			} catch (error) {
+				console.warn("[Mastra Factory] Could not record environment setup results", {
+					orgId: session.orgId,
+					sessionId: session.sessionId,
+					error: error instanceof Error ? error.message : String(error)
+				});
+			}
+		};
 		const sessionSandbox = requireExec(sessionEntry.sandbox);
 		const filesystem = new SandboxFilesystem({
 			id: `sandbox-fs:${workspaceId}`,
 			sandbox: sessionSandbox,
-			workdir: () => resolveSessionWorkdir(session.id, sessionEntry.sandbox, repoFullName)
+			workdir: async () => {
+				const checkout = await resolveSessionWorkdir(session.id, sessionEntry.sandbox, repoFullName);
+				return sessionWorkdir(checkout) ?? checkout;
+			}
 		});
-		const projectSkillPaths = [
+		const skillRoots = [
 			path.join(configDir, "skills"),
 			".claude/skills",
 			".agents/skills"
 		];
+		const projectSkillPaths = checkoutDirs ? checkoutDirs.flatMap((dir) => skillRoots.map((skillPath) => path.posix.join(dir, skillPath))) : skillRoots;
 		const guardedSkillFallback = new UnmaterializedAwareSkillSource(filesystem, () => sessionEntry.sandbox.status === "running");
 		const workspace = new Workspace({
 			id: workspaceId,
@@ -663,6 +982,7 @@ function createWorkspaceFactory(options = {}) {
 			skillCacheReviewState.delete(workspaceId);
 			skillReviewChecks.delete(workspaceId);
 			evictSessionSandbox(session.id);
+			clearSessionEnvironment(session.sessionId);
 			await mastra?.removeWorkspace?.(workspaceId);
 		})) throw new Error(`Factory session ${session.sessionId} was retired during workspace materialization`);
 		fireEagerStart();
@@ -670,6 +990,6 @@ function createWorkspaceFactory(options = {}) {
 	};
 }
 //#endregion
-export { BUNDLED_FACTORY_SKILLS_PATH, FACTORY_SKILL_NAMES, FactorySkillSource, FactoryWorkspaceRegistry, REVIEW_ONLY_FACTORY_SKILLS, createWorkspaceFactory, rescanFactorySkills, resolveLocalFactorySkillsPath };
+export { BUNDLED_FACTORY_SKILLS_PATH, FACTORY_SKILL_NAMES, FactorySkillSource, FactoryWorkspaceRegistry, REVIEW_ONLY_FACTORY_SKILLS, createWorkspaceFactory, environmentSandboxContext, rescanFactorySkills, resolveLocalFactorySkillsPath, resolveProjectEnvironment };
 
 //# sourceMappingURL=workspace.js.map