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

package/dist/sandbox/callback-factory-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-factory-sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/callback-factory-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEnF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAEvE;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;;IAC/E,QAAQ,CAAC,QAAQ,YAAY;gBAIjB,QAAQ,EAAE,0BAA0B;IAKhD,MAAM,CAAC,GAAG,EAAE,qBAAqB,GAAG,aAAa;CAGlD"}

package/dist/sandbox/callback-factory-sandbox.js

@@ -0,0 +1,22 @@
+import { FactorySandbox } from "@mastra/core/workspace";
+//#region src/sandbox/callback-factory-sandbox.ts
+/**
+* Wraps the `sandbox: ctx => new SomeSandbox(...)` host callback
+* as a FactorySandbox. The host owns everything inside the callback, so the
+* factory knows nothing about it: no settings, no template, no builds.
+*/
+var CallbackFactorySandbox = class extends FactorySandbox {
+	provider = "custom";
+	#callback;
+	constructor(callback) {
+		super();
+		this.#callback = callback;
+	}
+	create(ctx) {
+		return this.#callback(ctx);
+	}
+};
+//#endregion
+export { CallbackFactorySandbox };
+
+//# sourceMappingURL=callback-factory-sandbox.js.map

package/dist/sandbox/callback-factory-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-factory-sandbox.js","names":["#callback"],"sources":["../../src/sandbox/callback-factory-sandbox.ts"],"sourcesContent":["import { FactorySandbox } from '@mastra/core/workspace';\nimport type { FactorySandboxContext, MastraSandbox } from '@mastra/core/workspace';\n\nimport type { MastraFactorySandboxConfig } from './session-sandbox.js';\n\n/**\n * Wraps the `sandbox: ctx => new SomeSandbox(...)` host callback\n * as a FactorySandbox. The host owns everything inside the callback, so the\n * factory knows nothing about it: no settings, no template, no builds.\n */\nexport class CallbackFactorySandbox extends FactorySandbox<Record<string, never>> {\n  readonly provider = 'custom';\n\n  readonly #callback: MastraFactorySandboxConfig;\n\n  constructor(callback: MastraFactorySandboxConfig) {\n    super();\n    this.#callback = callback;\n  }\n\n  create(ctx: FactorySandboxContext): MastraSandbox {\n    return this.#callback(ctx);\n  }\n}\n"],"mappings":";;;;;;;AAUA,IAAa,yBAAb,cAA4C,eAAsC;CAChF,WAAoB;CAEpB;CAEA,YAAY,UAAsC;EAChD,MAAM;EACN,KAAKA,YAAY;CACnB;CAEA,OAAO,KAA2C;EAChD,OAAO,KAAKA,UAAU,GAAG;CAC3B;AACF"}

package/dist/sandbox/local-factory-sandbox.d.ts

@@ -0,0 +1,20 @@
+import { FactorySandbox, LocalSandbox } from '@mastra/core/workspace';
+import type { FactorySandboxContext } from '@mastra/core/workspace';
+export interface LocalFactorySandboxOptions {
+    /** Directory under which every session gets its own working directory. */
+    root: string;
+    /** Environment for commands run in the sandbox. */
+    env?: Record<string, string>;
+}
+/**
+ * Sessions run on the host machine: each session's sandbox is a LocalSandbox
+ * rooted at `join(root, sessionId)`, where the repository checks out as a
+ * subdirectory. No template and no user-tunable settings.
+ */
+export declare class LocalFactorySandbox extends FactorySandbox<Record<string, never>> {
+    #private;
+    readonly provider = "local";
+    constructor(options: LocalFactorySandboxOptions);
+    create(ctx: FactorySandboxContext): LocalSandbox;
+}
+//# sourceMappingURL=local-factory-sandbox.d.ts.map

package/dist/sandbox/local-factory-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-factory-sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/local-factory-sandbox.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,MAAM,WAAW,0BAA0B;IACzC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;;IAC5E,QAAQ,CAAC,QAAQ,WAAW;gBAIhB,OAAO,EAAE,0BAA0B;IAK/C,MAAM,CAAC,GAAG,EAAE,qBAAqB,GAAG,YAAY;CAOjD"}

package/dist/sandbox/local-factory-sandbox.js

@@ -0,0 +1,27 @@
+import { FactorySandbox, LocalSandbox } from "@mastra/core/workspace";
+import { join } from "path";
+//#region src/sandbox/local-factory-sandbox.ts
+/**
+* Sessions run on the host machine: each session's sandbox is a LocalSandbox
+* rooted at `join(root, sessionId)`, where the repository checks out as a
+* subdirectory. No template and no user-tunable settings.
+*/
+var LocalFactorySandbox = class extends FactorySandbox {
+	provider = "local";
+	#options;
+	constructor(options) {
+		super();
+		this.#options = options;
+	}
+	create(ctx) {
+		return new LocalSandbox({
+			id: ctx.sessionId,
+			workingDirectory: join(this.#options.root, ctx.sessionId),
+			...this.#options.env ? { env: this.#options.env } : {}
+		});
+	}
+};
+//#endregion
+export { LocalFactorySandbox };
+
+//# sourceMappingURL=local-factory-sandbox.js.map

package/dist/sandbox/local-factory-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-factory-sandbox.js","names":["#options"],"sources":["../../src/sandbox/local-factory-sandbox.ts"],"sourcesContent":["import { join } from 'node:path';\nimport { FactorySandbox, LocalSandbox } from '@mastra/core/workspace';\nimport type { FactorySandboxContext } from '@mastra/core/workspace';\n\nexport interface LocalFactorySandboxOptions {\n  /** Directory under which every session gets its own working directory. */\n  root: string;\n  /** Environment for commands run in the sandbox. */\n  env?: Record<string, string>;\n}\n\n/**\n * Sessions run on the host machine: each session's sandbox is a LocalSandbox\n * rooted at `join(root, sessionId)`, where the repository checks out as a\n * subdirectory. No template and no user-tunable settings.\n */\nexport class LocalFactorySandbox extends FactorySandbox<Record<string, never>> {\n  readonly provider = 'local';\n\n  readonly #options: LocalFactorySandboxOptions;\n\n  constructor(options: LocalFactorySandboxOptions) {\n    super();\n    this.#options = options;\n  }\n\n  create(ctx: FactorySandboxContext): LocalSandbox {\n    return new LocalSandbox({\n      id: ctx.sessionId,\n      workingDirectory: join(this.#options.root, ctx.sessionId),\n      ...(this.#options.env ? { env: this.#options.env } : {}),\n    });\n  }\n}\n"],"mappings":";;;;;;;;AAgBA,IAAa,sBAAb,cAAyC,eAAsC;CAC7E,WAAoB;CAEpB;CAEA,YAAY,SAAqC;EAC/C,MAAM;EACN,KAAKA,WAAW;CAClB;CAEA,OAAO,KAA0C;EAC/C,OAAO,IAAI,aAAa;GACtB,IAAI,IAAI;GACR,kBAAkB,KAAK,KAAKA,SAAS,MAAM,IAAI,SAAS;GACxD,GAAI,KAAKA,SAAS,MAAM,EAAE,KAAK,KAAKA,SAAS,IAAI,IAAI,CAAC;EACxD,CAAC;CACH;AACF"}

package/dist/sandbox/session-retirement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-retirement.d.ts","sourceRoot":"","sources":["../../src/sandbox/session-retirement.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,0BAA0B,EAC3B,MAAM,2CAA2C,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAI9E,KAAK,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAEjF,MAAM,WAAW,mCAAmC;IAClD,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAChE,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,0BAA0B,CAAC;IAC1C,8EAA8E;IAC9E,SAAS,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,wBAAwB,CAAC,CAAC;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;CACxB;AAQD;;;;;;;;;;GAUG;AACH,qBAAa,4BAA4B;;gBAK3B,OAAO,GAAE,mCAAwC;IAKvD,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvD,sBAAsB,CAAC,OAAO,EAAE;QACpC,SAAS,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;QACzC,aAAa,EAAE,0BAA0B,CAAC;QAC1C,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBX,+BAA+B,CAAC,OAAO,EAAE;QAC7C,aAAa,EAAE,0BAA0B,CAAC;QAC1C,SAAS,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,wBAAwB,CAAC,CAAC;QAC7D,KAAK,EAAE,MAAM,CAAC;QACd,mBAAmB,EAAE,MAAM,CAAC;KAC7B,GAAG,OAAO,CAAC,IAAI,CAAC;CA0FlB"}
+{"version":3,"file":"session-retirement.d.ts","sourceRoot":"","sources":["../../src/sandbox/session-retirement.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,0BAA0B,EAC3B,MAAM,2CAA2C,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAI9E,KAAK,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAEjF,MAAM,WAAW,mCAAmC;IAClD,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAChE,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,0BAA0B,CAAC;IAC1C,8EAA8E;IAC9E,SAAS,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,wBAAwB,CAAC,CAAC;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;CACxB;AAQD;;;;;;;;;;GAUG;AACH,qBAAa,4BAA4B;;gBAK3B,OAAO,GAAE,mCAAwC;IAKvD,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvD,sBAAsB,CAAC,OAAO,EAAE;QACpC,SAAS,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;QACzC,aAAa,EAAE,0BAA0B,CAAC;QAC1C,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBX,+BAA+B,CAAC,OAAO,EAAE;QAC7C,aAAa,EAAE,0BAA0B,CAAC;QAC1C,SAAS,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,wBAAwB,CAAC,CAAC;QAC7D,KAAK,EAAE,MAAM,CAAC;QACd,mBAAmB,EAAE,MAAM,CAAC;KAC7B,GAAG,OAAO,CAAC,IAAI,CAAC;CAqHlB"}

package/dist/sandbox/session-retirement.js

@@ -1,7 +1,8 @@
+import { DEFAULT_COMMAND_TIMEOUT_MS, runTeardownCommand } from "../integrations/github/sandbox.js";
 import { requireExec } from "./materialization.js";
 import { peekSessionSandbox } from "./session-sandbox.js";
+import { peekSessionEnvironmentTeardown } from "../session/environment-state-processor.js";
 import { releaseSessionSandbox } from "../integrations/github/sandbox-release.js";
-import { DEFAULT_COMMAND_TIMEOUT_MS, runTeardownCommand } from "../integrations/github/sandbox.js";
 //#region src/sandbox/session-retirement.ts
 function boundedError(error) {
 	const detail = error instanceof Error ? error.message : String(error);
@@ -88,12 +89,28 @@ var SessionRetirementCoordinator = class {
 	async #teardownSessionSandbox(input, session) {
 		const entry = peekSessionSandbox(session.id);
 		if (!entry) return;
+		const environmentTeardown = peekSessionEnvironmentTeardown(session.sessionId);
+		if (environmentTeardown.length > 0) {
+			for (const repo of environmentTeardown) try {
+				await runTeardownCommand(requireExec(entry.sandbox), repo.dir, repo.command, { timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS });
+			} catch (error) {
+				this.#warn("Factory teardown command failed", {
+					orgId: session.orgId,
+					sessionId: session.sessionId,
+					projectRepositoryId: session.projectRepositoryId,
+					repository: repo.slug,
+					error: boundedError(error)
+				});
+			}
+			await this.#releaseSandbox(input, session);
+			return;
+		}
 		let projectRepository;
 		try {
-			projectRepository = await input.sourceControl.projectRepositories.get({
+			projectRepository = session.projectRepositoryId ? await input.sourceControl.projectRepositories.get({
 				orgId: input.orgId,
 				id: session.projectRepositoryId
-			});
+			}) : null;
 		} catch (error) {
 			this.#warn("Factory repository settings could not be loaded for session retirement", {
 				orgId: session.orgId,
@@ -112,6 +129,9 @@ var SessionRetirementCoordinator = class {
 				error: boundedError(error)
 			});
 		}
+		await this.#releaseSandbox(input, session);
+	}
+	async #releaseSandbox(input, session) {
 		try {
 			await releaseSessionSandbox({
 				sessionId: session.id,

package/dist/sandbox/session-retirement.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-retirement.js","names":["#invalidateSession","#warn","#locks","#retireSession","#teardownSessionSandbox"],"sources":["../../src/sandbox/session-retirement.ts"],"sourcesContent":["import { releaseSessionSandbox } from '../integrations/github/sandbox-release.js';\nimport { DEFAULT_COMMAND_TIMEOUT_MS, runTeardownCommand } from '../integrations/github/sandbox.js';\nimport type {\n  ProjectRepository,\n  SourceControlSession,\n  SourceControlStorageHandle,\n} from '../storage/domains/source-control/base.js';\nimport type { WorkItemsStorage } from '../storage/domains/work-items/base.js';\nimport { requireExec } from './materialization.js';\nimport { peekSessionSandbox } from './session-sandbox.js';\n\ntype WarningLogger = (message: string, details: Record<string, unknown>) => void;\n\nexport interface SessionRetirementCoordinatorOptions {\n  invalidateSession?: (sessionId: string) => Promise<void> | void;\n  warn?: WarningLogger;\n}\n\nexport interface RetireSessionInput {\n  sourceControl: SourceControlStorageHandle;\n  /** When provided, deleting the session row also strips its work-item refs. */\n  workItems?: Pick<WorkItemsStorage, 'clearSessionReferences'>;\n  orgId: string;\n  sessionId: string;\n  deleteSession: boolean;\n}\n\nfunction boundedError(error: unknown): string {\n  const detail = error instanceof Error ? error.message : String(error);\n  if (detail.length <= 2000) return detail;\n  return `${detail.slice(0, 200)}...${detail.slice(-1797)}`;\n}\n\n/**\n * Owns terminal and destructive session cleanup. Each session is serialized so\n * duplicate role bindings and competing deletion/transition requests cannot\n * run teardown concurrently.\n *\n * Sandbox identity is the session id: retirement stops (or, for deleted\n * sessions, destroys) the sandbox this process holds in the session memo.\n * Sessions opened on another replica have no memo entry here — their VMs are\n * left to the provider's idle lifecycle (pause / idle GC), which is the\n * provider-owned half of the contract.\n */\nexport class SessionRetirementCoordinator {\n  readonly #invalidateSession: NonNullable<SessionRetirementCoordinatorOptions['invalidateSession']>;\n  readonly #warn: WarningLogger;\n  readonly #locks = new Map<string, Promise<void>>();\n\n  constructor(options: SessionRetirementCoordinatorOptions = {}) {\n    this.#invalidateSession = options.invalidateSession ?? (() => {});\n    this.#warn = options.warn ?? ((message, details) => console.warn(`[Mastra Factory] ${message}`, details));\n  }\n\n  async retireSession(input: RetireSessionInput): Promise<void> {\n    const previous = this.#locks.get(input.sessionId) ?? Promise.resolve();\n    const current = previous.catch(() => {}).then(() => this.#retireSession(input));\n    this.#locks.set(input.sessionId, current);\n    try {\n      await current;\n    } finally {\n      if (this.#locks.get(input.sessionId) === current) this.#locks.delete(input.sessionId);\n    }\n  }\n\n  async retireWorkItemSessions(options: {\n    workItems: Pick<WorkItemsStorage, 'get'>;\n    sourceControl: SourceControlStorageHandle;\n    orgId: string;\n    workItemId: string;\n  }): Promise<void> {\n    const item = await options.workItems.get({ orgId: options.orgId, id: options.workItemId });\n    if (!item) return;\n    const sessionIds = [...new Set(Object.values(item.sessions).map(session => session.sessionId))];\n    await Promise.all(\n      sessionIds.map(sessionId =>\n        this.retireSession({\n          sourceControl: options.sourceControl,\n          orgId: options.orgId,\n          sessionId,\n          deleteSession: false,\n        }),\n      ),\n    );\n  }\n\n  async retireProjectRepositorySessions(options: {\n    sourceControl: SourceControlStorageHandle;\n    workItems?: Pick<WorkItemsStorage, 'clearSessionReferences'>;\n    orgId: string;\n    projectRepositoryId: string;\n  }): Promise<void> {\n    const sessions = await options.sourceControl.sessions.listByProjectRepository({\n      projectRepositoryId: options.projectRepositoryId,\n    });\n    await Promise.all(\n      sessions.map(session =>\n        this.retireSession({\n          sourceControl: options.sourceControl,\n          ...(options.workItems ? { workItems: options.workItems } : {}),\n          orgId: options.orgId,\n          sessionId: session.sessionId,\n          deleteSession: true,\n        }),\n      ),\n    );\n  }\n\n  async #retireSession(input: RetireSessionInput): Promise<void> {\n    const session = await input.sourceControl.sessions.getBySessionId(input.sessionId);\n    if (!session || session.orgId !== input.orgId) return;\n\n    try {\n      await this.#teardownSessionSandbox(input, session);\n    } finally {\n      try {\n        await this.#invalidateSession(session.sessionId);\n      } catch (error) {\n        this.#warn('Factory session workspace cache invalidation failed', {\n          orgId: session.orgId,\n          sessionId: session.sessionId,\n          projectRepositoryId: session.projectRepositoryId,\n          error: boundedError(error),\n        });\n      }\n\n      if (input.deleteSession) {\n        // Refs first: clearing again is a no-op, but refs on a deleted row would dangle forever.\n        await input.workItems?.clearSessionReferences({ orgId: input.orgId, sessionId: input.sessionId });\n        await input.sourceControl.sessions.delete(session.id);\n      }\n    }\n  }\n\n  async #teardownSessionSandbox(input: RetireSessionInput, session: SourceControlSession): Promise<void> {\n    const entry = peekSessionSandbox(session.id);\n    if (!entry) return;\n\n    let projectRepository: ProjectRepository | null | undefined;\n    try {\n      projectRepository = await input.sourceControl.projectRepositories.get({\n        orgId: input.orgId,\n        id: session.projectRepositoryId,\n      });\n    } catch (error) {\n      this.#warn('Factory repository settings could not be loaded for session retirement', {\n        orgId: session.orgId,\n        sessionId: session.sessionId,\n        projectRepositoryId: session.projectRepositoryId,\n        error: boundedError(error),\n      });\n    }\n\n    // An unresolved workdir means the sandbox never started in this process:\n    // nothing was set up, so there is nothing for a teardown command to undo.\n    if (projectRepository?.teardownCommand && entry.workdir) {\n      try {\n        await runTeardownCommand(requireExec(entry.sandbox), entry.workdir, projectRepository.teardownCommand, {\n          timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,\n        });\n      } catch (error) {\n        this.#warn('Factory teardown command failed', {\n          orgId: session.orgId,\n          sessionId: session.sessionId,\n          projectRepositoryId: session.projectRepositoryId,\n          error: boundedError(error),\n        });\n      }\n    }\n\n    try {\n      await releaseSessionSandbox({ sessionId: session.id, destroy: input.deleteSession });\n    } catch (error) {\n      this.#warn('Factory session sandbox release failed', {\n        orgId: session.orgId,\n        sessionId: session.sessionId,\n        projectRepositoryId: session.projectRepositoryId,\n        error: boundedError(error),\n      });\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"session-retirement.js","names":["#invalidateSession","#warn","#locks","#retireSession","#teardownSessionSandbox","#releaseSandbox"],"sources":["../../src/sandbox/session-retirement.ts"],"sourcesContent":["import { releaseSessionSandbox } from '../integrations/github/sandbox-release.js';\nimport { DEFAULT_COMMAND_TIMEOUT_MS, runTeardownCommand } from '../integrations/github/sandbox.js';\nimport { peekSessionEnvironmentTeardown } from '../session/environment-state-processor.js';\nimport type {\n  ProjectRepository,\n  SourceControlSession,\n  SourceControlStorageHandle,\n} from '../storage/domains/source-control/base.js';\nimport type { WorkItemsStorage } from '../storage/domains/work-items/base.js';\nimport { requireExec } from './materialization.js';\nimport { peekSessionSandbox } from './session-sandbox.js';\n\ntype WarningLogger = (message: string, details: Record<string, unknown>) => void;\n\nexport interface SessionRetirementCoordinatorOptions {\n  invalidateSession?: (sessionId: string) => Promise<void> | void;\n  warn?: WarningLogger;\n}\n\nexport interface RetireSessionInput {\n  sourceControl: SourceControlStorageHandle;\n  /** When provided, deleting the session row also strips its work-item refs. */\n  workItems?: Pick<WorkItemsStorage, 'clearSessionReferences'>;\n  orgId: string;\n  sessionId: string;\n  deleteSession: boolean;\n}\n\nfunction boundedError(error: unknown): string {\n  const detail = error instanceof Error ? error.message : String(error);\n  if (detail.length <= 2000) return detail;\n  return `${detail.slice(0, 200)}...${detail.slice(-1797)}`;\n}\n\n/**\n * Owns terminal and destructive session cleanup. Each session is serialized so\n * duplicate role bindings and competing deletion/transition requests cannot\n * run teardown concurrently.\n *\n * Sandbox identity is the session id: retirement stops (or, for deleted\n * sessions, destroys) the sandbox this process holds in the session memo.\n * Sessions opened on another replica have no memo entry here — their VMs are\n * left to the provider's idle lifecycle (pause / idle GC), which is the\n * provider-owned half of the contract.\n */\nexport class SessionRetirementCoordinator {\n  readonly #invalidateSession: NonNullable<SessionRetirementCoordinatorOptions['invalidateSession']>;\n  readonly #warn: WarningLogger;\n  readonly #locks = new Map<string, Promise<void>>();\n\n  constructor(options: SessionRetirementCoordinatorOptions = {}) {\n    this.#invalidateSession = options.invalidateSession ?? (() => {});\n    this.#warn = options.warn ?? ((message, details) => console.warn(`[Mastra Factory] ${message}`, details));\n  }\n\n  async retireSession(input: RetireSessionInput): Promise<void> {\n    const previous = this.#locks.get(input.sessionId) ?? Promise.resolve();\n    const current = previous.catch(() => {}).then(() => this.#retireSession(input));\n    this.#locks.set(input.sessionId, current);\n    try {\n      await current;\n    } finally {\n      if (this.#locks.get(input.sessionId) === current) this.#locks.delete(input.sessionId);\n    }\n  }\n\n  async retireWorkItemSessions(options: {\n    workItems: Pick<WorkItemsStorage, 'get'>;\n    sourceControl: SourceControlStorageHandle;\n    orgId: string;\n    workItemId: string;\n  }): Promise<void> {\n    const item = await options.workItems.get({ orgId: options.orgId, id: options.workItemId });\n    if (!item) return;\n    const sessionIds = [...new Set(Object.values(item.sessions).map(session => session.sessionId))];\n    await Promise.all(\n      sessionIds.map(sessionId =>\n        this.retireSession({\n          sourceControl: options.sourceControl,\n          orgId: options.orgId,\n          sessionId,\n          deleteSession: false,\n        }),\n      ),\n    );\n  }\n\n  async retireProjectRepositorySessions(options: {\n    sourceControl: SourceControlStorageHandle;\n    workItems?: Pick<WorkItemsStorage, 'clearSessionReferences'>;\n    orgId: string;\n    projectRepositoryId: string;\n  }): Promise<void> {\n    const sessions = await options.sourceControl.sessions.listByProjectRepository({\n      projectRepositoryId: options.projectRepositoryId,\n    });\n    await Promise.all(\n      sessions.map(session =>\n        this.retireSession({\n          sourceControl: options.sourceControl,\n          ...(options.workItems ? { workItems: options.workItems } : {}),\n          orgId: options.orgId,\n          sessionId: session.sessionId,\n          deleteSession: true,\n        }),\n      ),\n    );\n  }\n\n  async #retireSession(input: RetireSessionInput): Promise<void> {\n    const session = await input.sourceControl.sessions.getBySessionId(input.sessionId);\n    if (!session || session.orgId !== input.orgId) return;\n\n    try {\n      await this.#teardownSessionSandbox(input, session);\n    } finally {\n      try {\n        await this.#invalidateSession(session.sessionId);\n      } catch (error) {\n        this.#warn('Factory session workspace cache invalidation failed', {\n          orgId: session.orgId,\n          sessionId: session.sessionId,\n          projectRepositoryId: session.projectRepositoryId,\n          error: boundedError(error),\n        });\n      }\n\n      if (input.deleteSession) {\n        // Refs first: clearing again is a no-op, but refs on a deleted row would dangle forever.\n        await input.workItems?.clearSessionReferences({ orgId: input.orgId, sessionId: input.sessionId });\n        await input.sourceControl.sessions.delete(session.id);\n      }\n    }\n  }\n\n  async #teardownSessionSandbox(input: RetireSessionInput, session: SourceControlSession): Promise<void> {\n    const entry = peekSessionSandbox(session.id);\n    if (!entry) return;\n\n    // A session booted from its factory environment tears every repository\n    // down in position order, each in its own directory; a failure is logged\n    // and the next repository still runs.\n    const environmentTeardown = peekSessionEnvironmentTeardown(session.sessionId);\n    if (environmentTeardown.length > 0) {\n      for (const repo of environmentTeardown) {\n        try {\n          await runTeardownCommand(requireExec(entry.sandbox), repo.dir, repo.command, {\n            timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,\n          });\n        } catch (error) {\n          this.#warn('Factory teardown command failed', {\n            orgId: session.orgId,\n            sessionId: session.sessionId,\n            projectRepositoryId: session.projectRepositoryId,\n            repository: repo.slug,\n            error: boundedError(error),\n          });\n        }\n      }\n      await this.#releaseSandbox(input, session);\n      return;\n    }\n\n    let projectRepository: ProjectRepository | null | undefined;\n    try {\n      projectRepository = session.projectRepositoryId\n        ? await input.sourceControl.projectRepositories.get({ orgId: input.orgId, id: session.projectRepositoryId })\n        : null;\n    } catch (error) {\n      this.#warn('Factory repository settings could not be loaded for session retirement', {\n        orgId: session.orgId,\n        sessionId: session.sessionId,\n        projectRepositoryId: session.projectRepositoryId,\n        error: boundedError(error),\n      });\n    }\n\n    // An unresolved workdir means the sandbox never started in this process:\n    // nothing was set up, so there is nothing for a teardown command to undo.\n    if (projectRepository?.teardownCommand && entry.workdir) {\n      try {\n        await runTeardownCommand(requireExec(entry.sandbox), entry.workdir, projectRepository.teardownCommand, {\n          timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,\n        });\n      } catch (error) {\n        this.#warn('Factory teardown command failed', {\n          orgId: session.orgId,\n          sessionId: session.sessionId,\n          projectRepositoryId: session.projectRepositoryId,\n          error: boundedError(error),\n        });\n      }\n    }\n\n    await this.#releaseSandbox(input, session);\n  }\n\n  async #releaseSandbox(input: RetireSessionInput, session: SourceControlSession): Promise<void> {\n    try {\n      await releaseSessionSandbox({ sessionId: session.id, destroy: input.deleteSession });\n    } catch (error) {\n      this.#warn('Factory session sandbox release failed', {\n        orgId: session.orgId,\n        sessionId: session.sessionId,\n        projectRepositoryId: session.projectRepositoryId,\n        error: boundedError(error),\n      });\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/sandbox/session-sandbox.d.ts

@@ -1,43 +1,12 @@
-import type { MastraSandbox, SandboxStartHook, WorkspaceSandbox } from '@mastra/core/workspace';
-import type { RepositoryAccess } from '../capabilities/version-control.js';
+import type { FactorySandbox, FactorySandboxContext as CoreFactorySandboxContext, MastraSandbox, SandboxStartHook, WorkspaceSandbox } from '@mastra/core/workspace';
 /**
- * Everything factory knows about a session's sandbox needs — the whole
- * contract between factory and the deployer's sandbox callback. Factory owns
- * intent; the provider owns resolving `sessionId` to a runnable VM.
+ * Everything factory knows about a session's sandbox needs: the whole contract
+ * between factory and the host's FactorySandbox. Factory owns intent; the
+ * provider owns resolving `sessionId` to a runnable VM. Defined in
+ * `@mastra/core/workspace` so provider packages can implement it without
+ * depending on factory.
  */
-export interface FactorySandboxContext {
-    /** Stable session id — the sandbox identity. */
-    sessionId: string;
-    /**
-     * The provider's physical sandbox id persisted from a prior start, when the
-     * session has been started before. Providers that reattach by physical id
-     * (e.g. Railway) MUST forward it to the sandbox constructor so resume
-     * reattaches the original VM instead of provisioning a replacement. E2B and
-     * Platform accept it as a deterministic-reattach optimization. Undefined on
-     * a session's first ever start.
-     */
-    sandboxId?: string;
-    /** owner/name of the repository, when the session is repo-backed. */
-    repoFullName?: string;
-    /**
-     * Configured repo setup command, when present. Part of a repo template's
-     * identity: a different setup command produces a different template.
-     */
-    setupCommand?: string;
-    /**
-     * Resolves the session repository's clone URL and a fresh short-lived
-     * credential for it. Providers use it for authenticated work that runs
-     * outside the VM — resolving a private repo's head, or cloning it during
-     * a template build. The credential is minted per call (installation
-     * tokens expire in ~1h); never an org PAT.
-     *
-     * `undefined` when the session has no repository, which is how a provider
-     * knows to build no repo template. The key is always present so that
-     * passing the whole context to a provider helper keeps working when this
-     * field changes, instead of silently resolving to "no repository".
-     */
-    getRepositoryAccess: (() => Promise<RepositoryAccess>) | undefined;
-}
+export type FactorySandboxContext = CoreFactorySandboxContext;
 /**
  * The deploy's sandbox configuration: construct a session's sandbox from
  * intent. The sandbox identity is the session id; the provider must honor
@@ -62,8 +31,17 @@ export interface FactorySandboxContext {
  * ```typescript
  * sandbox: ({ sessionId, sandboxId }) => new E2BSandbox({ id: sessionId, sandboxId })
  * ```
+ *
+ * A FactorySandbox instance (for example `new E2BFactorySandbox({ apiKey })`)
+ * additionally exposes settings and template builds to the environment.
  */
 export type MastraFactorySandboxConfig = (ctx: FactorySandboxContext) => MastraSandbox;
+/**
+ * The `sandbox` option of `MastraFactoryConfig`: a FactorySandbox instance
+ * (it owns the session sandbox constructor, the repo template and the
+ * environment settings schema) or a bare callback, which the factory wraps as a `provider: 'custom'` sandbox with no settings.
+ */
+export type MastraFactorySandboxOption = FactorySandbox | MastraFactorySandboxConfig;
 /**
  * What the start hook learned about the setup command before running the
  * session setup, and how to record its completion afterwards.
@@ -80,6 +58,27 @@ export interface SessionSetupGate {
  * still needs its pull); only the setup command consults `gate`.
  */
 export type SessionSetupRun = (sandbox: WorkspaceSandbox, workdir: string, gate: SessionSetupGate) => Promise<void>;
+/** One environment repository as the boot hook needs it: its slug and setup command. */
+export interface SessionEnvironmentRepository {
+    slug: string;
+    setupCommand?: string;
+}
+/** What the environment hook learned about one repository before the boot runs. */
+export interface SessionEnvironmentRepositoryGate extends SessionEnvironmentRepository {
+    /** `<root>/<repoDir>`, the directory the template cloned this repository into. */
+    dir: string;
+    gate: SessionSetupGate;
+}
+/** The environment hook's view of the workspace: the root, every repository in position order, the workspace gate. */
+export interface SessionEnvironmentGate {
+    /** The workspace root, parent of every repository directory. */
+    root: string;
+    repos: SessionEnvironmentRepositoryGate[];
+    /** Gate for `workspaceSetupCommand`; `setupDone` when there is no command or its marker matches. */
+    workspace: SessionSetupGate;
+}
+/** The list-form session boot: run on every start, like `SessionSetupRun`. */
+export type SessionEnvironmentSetupRun = (sandbox: WorkspaceSandbox, environment: SessionEnvironmentGate) => Promise<void>;
 /**
  * Per-process session-id → sandbox instance memo.
  *
@@ -100,14 +99,38 @@ interface SessionSandboxEntry {
      * treat an unresolved workdir as "nothing materialized".
      */
     workdir?: string;
+    /** The session's own repository, the only one `workdir` is ever recorded for. */
+    ownRepo: string;
+    /** Environment repositories in position order; the session's own repository is among them. */
+    repos?: string[];
+}
+/** One environment repository as the file readers see it. */
+export interface SessionLayoutRepository {
+    slug: string;
+    /** Absolute checkout directory. */
+    dir: string;
+    /** Path prefix of this checkout under the layout root: empty for a single-repository session, `<dir>/` otherwise. */
+    prefix: string;
 }
+/**
+ * Where a session's files are read from. A session with one repository is
+ * rooted at that checkout, as before environments existed; a session with
+ * several is rooted at the workspace root with each checkout as a directory
+ * beneath it.
+ */
+export interface SessionLayout {
+    root: string;
+    repos: SessionLayoutRepository[];
+}
+/** The layout of a memoized session, `undefined` until its workdir resolved. */
+export declare function sessionLayout(entry: SessionSandboxEntry | undefined): SessionLayout | undefined;
 /**
  * Get the session's memoized sandbox entry, constructing (and memoizing) it on
  * first access. Construction is cheap and side-effect-free by contract; VMs
  * are provisioned on `start()` only. Local sandboxes get their workdir here;
  * remote workdirs are a runtime fact of the VM, resolved on first start.
  */
-export declare function getSessionSandbox(sessionId: string, repoFullName: string, construct: () => WorkspaceSandbox): SessionSandboxEntry;
+export declare function getSessionSandbox(sessionId: string, repoFullName: string, construct: () => WorkspaceSandbox, repos?: string[]): SessionSandboxEntry;
 /**
  * Resolve (and memoize on the session entry) the session's repo checkout
  * root. Local sandboxes answer synchronously from their configured
@@ -115,7 +138,9 @@ export declare function getSessionSandbox(sessionId: string, repoFullName: strin
  * so the first resolution probes it with one `pwd` — the VM tells us where
  * home is, we never invent a path. Calling this against a stopped sandbox
  * lazily starts it (the probe is a command), so passive readers must peek
- * `entry.workdir` instead.
+ * `entry.workdir` instead. The memo is the session's own checkout; another
+ * environment repository lives beside it under the same root, so it is
+ * answered from the memo's parent without a second probe.
  */
 export declare function resolveSessionWorkdir(sessionId: string, sandbox: WorkspaceSandbox, repoFullName: string): Promise<string>;
 /**
@@ -139,5 +164,22 @@ export declare function hasFailedSetupCommand(sessionId: string, command: string
  * fails `start()` loudly; core treats onStart errors as fatal.
  */
 export declare function createSessionSetupHook(run: SessionSetupRun, sessionId: string, repoFullName: string, setupCommand: string | undefined): SandboxStartHook;
+/**
+ * The list-form start hook for a session whose factory has an environment:
+ * the same lifecycle as `createSessionSetupHook`, with one gate per
+ * repository plus one for the workspace setup command. The markers are the
+ * ones the multi-repo templates write (`.mastra-sandbox/repos/<repoDir>`,
+ * `.mastra-sandbox/workspace-setup`, `.mastra-sandbox/setup-failed`), all
+ * under the workspace root, which is the parent of the primary repository's
+ * directory: `resolveSessionWorkdir` keeps answering that directory so the
+ * PR tools and passive readers see the primary checkout, and the root is
+ * derived from it rather than probed twice.
+ *
+ * `repos` is in position order and must include the primary (`repoFullName`).
+ */
+export declare function createEnvironmentSetupHook(run: SessionEnvironmentSetupRun, sessionId: string, repoFullName: string, environment: {
+    repos: SessionEnvironmentRepository[];
+    workspaceSetupCommand?: string;
+}): SandboxStartHook;
 export {};
 //# sourceMappingURL=session-sandbox.d.ts.map

package/dist/sandbox/session-sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/session-sandbox.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAI3E;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,mBAAmB,EAAE,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC,GAAG,SAAS,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,GAAG,EAAE,qBAAqB,KAAK,aAAa,CAAC;AAEvF;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpH;;;;;;;;;GASG;AACH,UAAU,mBAAmB;IAC3B,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,gBAAgB,GAChC,mBAAmB,CAQrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CASjB;AAmBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAErF;AAED,uFAAuF;AACvF,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAG3D;AAED,4DAA4D;AAC5D,wBAAgB,+BAA+B,IAAI,IAAI,CAGtD;AAcD,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjF;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEjF;AAqCD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,gBAAgB,CAyBlB"}
+{"version":3,"file":"session-sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/session-sandbox.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/session-sandbox.js

@@ -1,23 +1,53 @@
 import { timedPhase } from "../timing.js";
-import { SETUP_MARKER_PATH, setupMarkerContent } from "../packages/_internals/workspace/dist/index.js";
-import { deriveLocalWorkdir, deriveRemoteRepoDir, repoDirUnder } from "./workdir.js";
+import { SETUP_FAILED_MARKER_PATH, SETUP_MARKER_PATH, WORKSPACE_SETUP_MARKER_PATH, repoSetupMarkerPath, setupMarkerContent } from "../packages/_internals/workspace/dist/index.js";
+import { deriveLocalWorkdir, deriveRemoteRepoDir, repoDirUnder, repositoryDirectoryName } from "./workdir.js";
 import path from "path";
 //#region src/sandbox/session-sandbox.ts
 const sessionSandboxes = /* @__PURE__ */ new Map();
+/** The layout of a memoized session, `undefined` until its workdir resolved. */
+function sessionLayout(entry) {
+	if (!entry?.workdir) return void 0;
+	const slugs = entry.repos?.length ? entry.repos : [entry.ownRepo];
+	if (slugs.length === 1) return {
+		root: entry.workdir,
+		repos: [{
+			slug: slugs[0],
+			dir: entry.workdir,
+			prefix: ""
+		}]
+	};
+	const root = path.posix.dirname(entry.workdir);
+	return {
+		root,
+		repos: slugs.map((slug) => {
+			const dir = slug.toLowerCase() === entry.ownRepo.toLowerCase() ? entry.workdir : repoDirUnder(root, slug);
+			return {
+				slug,
+				dir,
+				prefix: `${path.posix.basename(dir)}/`
+			};
+		})
+	};
+}
 /**
 * Get the session's memoized sandbox entry, constructing (and memoizing) it on
 * first access. Construction is cheap and side-effect-free by contract; VMs
 * are provisioned on `start()` only. Local sandboxes get their workdir here;
 * remote workdirs are a runtime fact of the VM, resolved on first start.
 */
-function getSessionSandbox(sessionId, repoFullName, construct) {
+function getSessionSandbox(sessionId, repoFullName, construct, repos) {
 	const existing = sessionSandboxes.get(sessionId);
-	if (existing) return existing;
+	if (existing) {
+		if (repos) existing.repos = repos;
+		return existing;
+	}
 	const sandbox = construct();
 	const local = deriveLocalWorkdir(sandbox, repoFullName);
 	const entry = {
 		sandbox,
-		...local ? { workdir: local } : {}
+		ownRepo: repoFullName,
+		...local ? { workdir: local } : {},
+		...repos ? { repos } : {}
 	};
 	sessionSandboxes.set(sessionId, entry);
 	return entry;
@@ -29,13 +59,20 @@ function getSessionSandbox(sessionId, repoFullName, construct) {
 * so the first resolution probes it with one `pwd` — the VM tells us where
 * home is, we never invent a path. Calling this against a stopped sandbox
 * lazily starts it (the probe is a command), so passive readers must peek
-* `entry.workdir` instead.
+* `entry.workdir` instead. The memo is the session's own checkout; another
+* environment repository lives beside it under the same root, so it is
+* answered from the memo's parent without a second probe.
 */
 async function resolveSessionWorkdir(sessionId, sandbox, repoFullName) {
 	const entry = sessionSandboxes.get(sessionId);
-	if (entry?.workdir && entry.sandbox === sandbox) return entry.workdir;
+	const memo = entry && entry.sandbox === sandbox ? entry : void 0;
+	if (memo && memo.ownRepo !== repoFullName) {
+		const own = await resolveSessionWorkdir(sessionId, sandbox, memo.ownRepo);
+		return repoDirUnder(path.posix.dirname(own), repoFullName);
+	}
+	if (memo?.workdir) return memo.workdir;
 	const workdir = deriveLocalWorkdir(sandbox, repoFullName) ?? deriveRemoteRepoDir(sandbox, repoFullName) ?? repoDirUnder(await probeHome(sandbox), repoFullName);
-	if (entry && entry.sandbox === sandbox) entry.workdir = workdir;
+	if (memo) memo.workdir = workdir;
 	return workdir;
 }
 /** One `pwd` in the VM's default shell cwd — its home dir, by provider convention. */
@@ -70,16 +107,18 @@ function __clearSessionSandboxesForTests() {
 * that triggered it. Recording it lets the next start skip the known-bad
 * command instead of wedging the session behind a permanently failing
 * onStart: clone and checkout still run, and the agent can fix or re-run
-* the setup itself. Keyed by the exact command so an edited setup command
-* runs fresh. In-memory only — a server restart re-runs the (idempotent)
+* the setup itself. Keyed by the exact command, one entry per failed command, so an
+* edited setup command runs fresh. In-memory only — a server restart re-runs the (idempotent)
 * setup.
 */
 const failedSetupCommands = /* @__PURE__ */ new Map();
 function recordFailedSetupCommand(sessionId, command) {
-	failedSetupCommands.set(sessionId, command);
+	const failed = failedSetupCommands.get(sessionId) ?? /* @__PURE__ */ new Set();
+	failed.add(command);
+	failedSetupCommands.set(sessionId, failed);
 }
 function hasFailedSetupCommand(sessionId, command) {
-	return failedSetupCommands.get(sessionId) === command;
+	return failedSetupCommands.get(sessionId)?.has(command) ?? false;
 }
 /**
 * The setup completion marker is a convention shared with the repo templates
@@ -125,7 +164,85 @@ function createSessionSetupHook(run, sessionId, repoFullName, setupCommand) {
 		});
 	};
 }
+/**
+* Shell-quote one marker file's content. Marker contents are digests, but
+* the quoting keeps an edited command's digest from ever reaching the shell
+* unquoted.
+*/
+function shellQuote(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+* The list-form marker probe: trust a repository's marker only when its
+* checkout exists, the marker names this command, and the template did not
+* record the repository in `setup-failed` (a failed per-repo setup still
+* writes the marker because every step ran; the failure list says it failed).
+*/
+async function repoMarkerMatches(sandbox, root, repoDir, content) {
+	const marker = `${root}/${repoSetupMarkerPath(repoDir)}`;
+	const failed = `${root}/${SETUP_FAILED_MARKER_PATH}`;
+	return (await sandbox.executeCommand(`test -d "${root}/${repoDir}/.git" && test -f "${marker}" && [ "$(cat "${marker}")" = ${shellQuote(content)} ] && ! grep -qxF -- ${shellQuote(repoDir)} "${failed}" 2>/dev/null`)).exitCode === 0;
+}
+/** Write a repository's marker and drop it from `setup-failed`. Best-effort, like `writeMarker`. */
+async function writeRepoMarker(sandbox, root, repoDir, content) {
+	const marker = `${root}/${repoSetupMarkerPath(repoDir)}`;
+	const failed = `${root}/${SETUP_FAILED_MARKER_PATH}`;
+	await sandbox.executeCommand(`mkdir -p "$(dirname "${marker}")" && printf '%s' ${shellQuote(content)} > "${marker}" && { test -f "${failed}" && { grep -vxF -- ${shellQuote(repoDir)} "${failed}" > "${failed}.tmp" || true; } && mv "${failed}.tmp" "${failed}" || true; }`).catch(() => {});
+}
+async function workspaceMarkerMatches(sandbox, root, content) {
+	const marker = `${root}/${WORKSPACE_SETUP_MARKER_PATH}`;
+	return (await sandbox.executeCommand(`test -f "${marker}" && [ "$(cat "${marker}")" = ${shellQuote(content)} ]`)).exitCode === 0;
+}
+async function writeWorkspaceMarker(sandbox, root, content) {
+	const marker = `${root}/${WORKSPACE_SETUP_MARKER_PATH}`;
+	await sandbox.executeCommand(`mkdir -p "$(dirname "${marker}")" && printf '%s' ${shellQuote(content)} > "${marker}"`).catch(() => {});
+}
+/**
+* The list-form start hook for a session whose factory has an environment:
+* the same lifecycle as `createSessionSetupHook`, with one gate per
+* repository plus one for the workspace setup command. The markers are the
+* ones the multi-repo templates write (`.mastra-sandbox/repos/<repoDir>`,
+* `.mastra-sandbox/workspace-setup`, `.mastra-sandbox/setup-failed`), all
+* under the workspace root, which is the parent of the primary repository's
+* directory: `resolveSessionWorkdir` keeps answering that directory so the
+* PR tools and passive readers see the primary checkout, and the root is
+* derived from it rather than probed twice.
+*
+* `repos` is in position order and must include the primary (`repoFullName`).
+*/
+function createEnvironmentSetupHook(run, sessionId, repoFullName, environment) {
+	const workspaceCommand = environment.workspaceSetupCommand?.trim() ? environment.workspaceSetupCommand : void 0;
+	const workspaceMarker = workspaceCommand ? setupMarkerContent(workspaceCommand) : void 0;
+	return async ({ sandbox }) => {
+		if (!sandbox.executeCommand) throw new Error(`Sandbox '${sandbox.id}' cannot run the session setup: no executeCommand implementation`);
+		const workdir = await resolveSessionWorkdir(sessionId, sandbox, repoFullName);
+		const root = path.posix.dirname(workdir);
+		const repos = [];
+		for (const repo of environment.repos) {
+			const repoDir = repositoryDirectoryName(repo.slug);
+			const marker = repo.setupCommand?.trim() ? setupMarkerContent(repo.setupCommand) : void 0;
+			const setupDone = marker ? await timedPhase(`workspace.setup-marker(${repoDir})`, () => repoMarkerMatches(sandbox, root, repoDir, marker)) : true;
+			if (marker) process.stderr.write(`[factory:setup] ${repo.slug}: ${setupDone ? "marker matches, skipping setup command" : "no matching marker, setup command will run"} (${root}/${repoSetupMarkerPath(repoDir)})\n`);
+			repos.push({
+				...repo,
+				dir: `${root}/${repoDir}`,
+				gate: {
+					setupDone,
+					markSetupDone: () => marker ? writeRepoMarker(sandbox, root, repoDir, marker) : Promise.resolve()
+				}
+			});
+		}
+		await run(sandbox, {
+			root,
+			repos,
+			workspace: {
+				setupDone: workspaceMarker ? await timedPhase("workspace.setup-marker(workspace)", () => workspaceMarkerMatches(sandbox, root, workspaceMarker)) : true,
+				markSetupDone: () => workspaceMarker ? writeWorkspaceMarker(sandbox, root, workspaceMarker) : Promise.resolve()
+			}
+		});
+	};
+}
 //#endregion
-export { __clearSessionSandboxesForTests, createSessionSetupHook, evictSessionSandbox, getSessionSandbox, hasFailedSetupCommand, peekSessionSandbox, recordFailedSetupCommand, resolveSessionWorkdir };
+export { __clearSessionSandboxesForTests, createEnvironmentSetupHook, createSessionSetupHook, evictSessionSandbox, getSessionSandbox, hasFailedSetupCommand, peekSessionSandbox, recordFailedSetupCommand, resolveSessionWorkdir, sessionLayout };
 
 //# sourceMappingURL=session-sandbox.js.map