@mastra/factory 0.0.0-aggregate-trace-20261015182851

package/dist/integrations/github/sandbox.js

@@ -0,0 +1,947 @@
+import { timedPhase } from "../../timing.js";
+import { isValidGitRef } from "../../sandbox/git-ref.js";
+//#region src/integrations/github/sandbox.ts
+/**
+* Single-quote a string for safe POSIX shell interpolation. Wraps the value in
+* single quotes and escapes any embedded single quote using the canonical
+* close-quote / escaped-quote / reopen-quote sequence (`'\''`). This is the
+* standard POSIX-safe construction and prevents the quoted string from being
+* terminated early.
+*/
+function shellQuote(value) {
+	return `'` + value.split(`'`).join(`'\\''`) + `'`;
+}
+/**
+* Default hang guard for sandbox shell commands. Generous by design — large
+* clones and dependency installs legitimately take minutes; the guard exists
+* so a wedged sandbox surfaces a failure instead of hanging the request that
+* triggered materialization forever.
+*/
+const DEFAULT_COMMAND_TIMEOUT_MS = 15 * 6e4;
+/** Branch checkout only fetches one ref — a much tighter budget applies. */
+const CHECKOUT_COMMAND_TIMEOUT_MS = 5 * 6e4;
+/**
+* A thrown transport-level failure that is worth retrying: remote sandbox
+
+* providers (e.g. the platform workspace proxy) surface transient 5xx errors
+* as exceptions carrying an HTTP `status` — typically while a freshly
+* provisioned VM is still coming up. Command failures are NOT exceptions
+* (they resolve with a non-zero exit code), so retrying here never re-runs a
+* command that the sandbox already executed and rejected.
+*/
+function isTransientTransportError(error) {
+	const status = error?.status;
+	return typeof status === "number" && status >= 500;
+}
+const SH_RETRIES = 2;
+const SH_RETRY_DELAY_MS = 2e3;
+/**
+* Run a shell script in the sandbox via `sh -c`. This is reserved for the
+* explicitly configured repository lifecycle hooks; programmatic commands use
+* {@link execute} with an argv array.
+*/
+async function sh(sandbox, script, options = {}) {
+	return execute(sandbox, "sh", ["-c", script], options);
+}
+/**
+* Execute one program with an argv array, bounded by a hang guard. Transient
+* sandbox transport failures are retried without ever interpolating arguments
+* into a shell command.
+*/
+async function execute(sandbox, command, args, options = {}) {
+	const deadlineMs = Date.now() + (options.timeoutMs ?? 9e5);
+	for (let attempt = 0;; attempt++) {
+		const started = performance.now();
+		try {
+			const result = await executeOnce(sandbox, command, args, {
+				...options,
+				timeoutMs: Math.max(deadlineMs - Date.now(), 1)
+			});
+			if (options.phase) process.stderr.write(`[factory:timing] ${options.phase} attempt=${attempt + 1} exit=${result.exitCode} ${Math.round(performance.now() - started)}ms\n`);
+			return result;
+		} catch (error) {
+			if (options.phase) process.stderr.write(`[factory:timing] ${options.phase} attempt=${attempt + 1} threw after ${Math.round(performance.now() - started)}ms: ${error instanceof Error ? error.message : String(error)}\n`);
+			if (attempt >= SH_RETRIES || !isTransientTransportError(error)) throw error;
+			const delayMs = SH_RETRY_DELAY_MS * (attempt + 1);
+			if (deadlineMs - Date.now() <= delayMs) throw error;
+			await new Promise((resolve) => setTimeout(resolve, delayMs));
+		}
+	}
+}
+/** Single structured command execution attempt, bounded by the hang guard. */
+async function executeOnce(sandbox, command, args, options) {
+	const timeoutMs = options.timeoutMs ?? 9e5;
+	let timer;
+	const hangGuard = new Promise((_, reject) => {
+		timer = setTimeout(() => {
+			const phase = options.phase ? ` during ${options.phase}` : "";
+			reject(/* @__PURE__ */ new Error(`Sandbox command timed out after ${Math.round(timeoutMs / 1e3)}s${phase}.`));
+		}, timeoutMs);
+		timer.unref?.();
+	});
+	try {
+		return await Promise.race([sandbox.executeCommand(command, args, {
+			timeout: timeoutMs,
+			...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+			...options.env !== void 0 ? { env: options.env } : {}
+		}), hangGuard]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+const GIT_TRANSFER_RETRIES = 2;
+const GIT_TRANSFER_RETRY_DELAY_MS = 2e3;
+/**
+* True when a git transfer died mid-flight rather than being refused.
+*
+* `sh` already retries transport errors the sandbox provider *throws*, but a
+* git command that reaches the network and then loses it exits non-zero
+* instead — so a single HTTP/2 framing glitch or dropped connection to
+* github.com would otherwise permanently fail opening a workspace. These
+* patterns all mean "the bytes stopped arriving", which says nothing about
+* whether the operation would succeed if attempted again.
+*
+* Deliberately narrow: a refusal (bad credentials, missing repo, blocked
+* egress) is terminal and must surface immediately rather than be retried into
+* a slow failure.
+*/
+function isTransientGitFailure(result) {
+	const output = `${result.stderr || ""}\n${result.stdout || ""}`;
+	return /HTTP2 framing layer|RPC failed; curl|RPC failed; HTTP 5\d\d|the remote end hung up unexpectedly|early EOF|unexpected disconnect|connection reset by peer|Recv failure|Send failure|GnuTLS recv error|TLS connection was non-properly terminated|502 Bad Gateway|503 Service Unavailable/i.test(output);
+}
+/**
+* Run a git command that only *reads* from the remote, retrying it when the
+* transfer dies mid-flight. Restricted to read-only transfers on purpose:
+* re-running a clone or a fetch is free, whereas re-running a push could
+* duplicate work already accepted by the remote before the connection dropped.
+*
+* `beforeRetry` lets a call site clear whatever the aborted attempt left
+* behind — a half-written clone directory blocks the next `git clone` outright.
+*/
+async function gitTransfer(sandbox, args, options = {}) {
+	const { beforeRetry, ...commandOptions } = options;
+	const deadlineMs = Date.now() + (commandOptions.timeoutMs ?? 9e5);
+	for (let attempt = 0;; attempt++) {
+		const result = await execute(sandbox, "git", args, {
+			...commandOptions,
+			timeoutMs: Math.max(deadlineMs - Date.now(), 1)
+		});
+		if (result.exitCode === 0 || attempt >= GIT_TRANSFER_RETRIES || !isTransientGitFailure(result)) return result;
+		process.stderr.write(`[factory:timing] git ${commandOptions.phase ?? "transfer"} retrying after attempt ${attempt + 1}\n`);
+		const delayMs = GIT_TRANSFER_RETRY_DELAY_MS * (attempt + 1);
+		if (deadlineMs - Date.now() <= delayMs) return result;
+		await new Promise((resolve) => setTimeout(resolve, delayMs));
+		await beforeRetry?.(attempt + 1);
+	}
+}
+/** Error raised when the sandbox cannot materialize the repo (actionable). */
+var MaterializeError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "MaterializeError";
+	}
+};
+function cleanUrl(repoFullName) {
+	return `https://github.com/${repoFullName}.git`;
+}
+function credentialScope(cloneUrl, code = "clone-failed") {
+	let url;
+	try {
+		url = new URL(cloneUrl);
+	} catch {
+		throw new MaterializeError("Refusing to configure credentials for an invalid repository clone URL.", code);
+	}
+	if (url.protocol !== "https:" || !url.hostname || url.username || url.password || url.search || url.hash) throw new MaterializeError("Refusing to configure credentials for an invalid repository clone URL.", code);
+	const repositoryPath = url.pathname.replace(/\/+$/, "");
+	if (!repositoryPath || repositoryPath === "/") throw new MaterializeError("Refusing to configure credentials for an invalid repository clone URL.", code);
+	return url.origin + repositoryPath;
+}
+/**
+* Provide HTTP Basic credentials to one Git process without putting a secret
+* in argv, a remote URL, or persistent git config. Git reads the URL-scoped
+* extra header from its process environment and discards it on exit.
+*/
+function gitAuthenticationEnvironment(cloneUrl, token, username, code = "clone-failed") {
+	const scope = credentialScope(cloneUrl, code);
+	if (!token || !username) throw new MaterializeError("Repository access did not include usable credentials.", code);
+	const authorization = Buffer.from(`${username}:${token}`, "utf8").toString("base64");
+	const alternate = scope.endsWith(".git") ? scope.slice(0, -4) : `${scope}.git`;
+	return {
+		GIT_CONFIG_COUNT: "2",
+		GIT_CONFIG_KEY_0: `http.${scope}.extraHeader`,
+		GIT_CONFIG_VALUE_0: `Authorization: Basic ${authorization}`,
+		GIT_CONFIG_KEY_1: `http.${alternate}.extraHeader`,
+		GIT_CONFIG_VALUE_1: `Authorization: Basic ${authorization}`,
+		GIT_TERMINAL_PROMPT: "0"
+	};
+}
+function normalizedRemoteUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return null;
+	}
+	if (url.protocol !== "https:" || !url.hostname || url.search || url.hash) return null;
+	const pathname = url.pathname.replace(/\/+$/, "").replace(/\.git$/i, "");
+	const repositoryPath = url.hostname.toLowerCase() === "github.com" ? pathname.toLowerCase() : pathname;
+	return "https://" + url.host.toLowerCase() + repositoryPath;
+}
+async function clearWorkdir(sandbox, workdir) {
+	const mkdir = await execute(sandbox, "mkdir", ["-p", workdir]);
+	if (mkdir.exitCode !== 0) throw classifyGitFailure(mkdir, "clone-failed");
+	const clear = await execute(sandbox, "find", [
+		workdir,
+		"-mindepth",
+		"1",
+		"-maxdepth",
+		"1",
+		"-exec",
+		"rm",
+		"-rf",
+		"--",
+		"{}",
+		"+"
+	]);
+	if (clear.exitCode !== 0) throw classifyGitFailure(clear, "clone-failed");
+}
+/**
+* Materialize the repo inside the user's sandbox: clone when no checkout of
+* this repo exists, otherwise nothing. Credentials are process-scoped and the
+* stored remote remains credential-free. Sets `materialized_at` on the
+* per-user sandbox binding row.
+*/
+async function materializeRepo(options) {
+	return timedPhase("workspace.materialize", () => materializeRepoImpl(options));
+}
+async function materializeRepoImpl(options) {
+	const { row: sandboxRow, repoInfo, sandbox, token, storage } = options;
+	const workdir = sandboxRow.sandboxWorkdir;
+	const repo = repoInfo.repoFullName;
+	if (!/^[\w.-]+(?:\/[\w.-]+)+$/.test(repo)) throw new MaterializeError(`Refusing to materialize: invalid repo full name '${repo}'.`, "clone-failed");
+	if (!/^[A-Za-z0-9_./-]+$/.test(repoInfo.defaultBranch)) throw new MaterializeError(`Refusing to materialize: invalid default branch '${repoInfo.defaultBranch}'.`, "clone-failed");
+	if ((await execute(sandbox, "git", ["--version"])).exitCode !== 0) throw new MaterializeError("git is not installed in the sandbox. The sandbox template must include git.", "git-missing");
+	const cleanCloneUrl = repoInfo.cloneUrl ?? cleanUrl(repo);
+	const existing = await existingCheckoutRemote(sandbox, workdir, cleanCloneUrl);
+	if (existing !== null) {
+		if (/\/\/[^/]*@/.test(existing)) await scrubRemote(sandbox, workdir, repo, cleanCloneUrl);
+	} else {
+		const authEnv = gitAuthenticationEnvironment(cleanCloneUrl, token, repoInfo.authUsername ?? "x-access-token", "clone-failed");
+		await clearWorkdir(sandbox, workdir);
+		const clone = await gitTransfer(sandbox, [
+			"clone",
+			"--depth=1",
+			"--single-branch",
+			"--branch",
+			repoInfo.defaultBranch,
+			"--",
+			cleanCloneUrl,
+			workdir
+		], {
+			env: authEnv,
+			phase: "repository clone",
+			beforeRetry: async () => {
+				await clearWorkdir(sandbox, workdir);
+			}
+		});
+		if (clone.exitCode !== 0) throw classifyGitFailure(clone, "clone-failed");
+	}
+	await storage.markMaterialized({ id: sandboxRow.id });
+}
+/**
+* Past file contents of a blob-less history load on demand; git asks gh, which
+* answers from the session's `GH_TOKEN`, so no credential is ever written.
+*/
+const GH_CREDENTIAL_HELPER = "!gh auth git-credential";
+async function fetchStartPoint(sandbox, workdir, { baseBranch, pullRequestNumber, mergeRequestNumber }, shallowClone, env) {
+	const changeRequestRef = pullRequestNumber !== void 0 ? `refs/pull/${pullRequestNumber}/head` : mergeRequestNumber !== void 0 ? `refs/merge-requests/${mergeRequestNumber}/head` : void 0;
+	const base = await gitTransfer(sandbox, [
+		"-C",
+		workdir,
+		"fetch",
+		...changeRequestRef && shallowClone ? ["--unshallow"] : [],
+		...pullRequestNumber !== void 0 ? ["--filter=blob:none"] : [],
+		"origin",
+		baseBranch
+	], {
+		env,
+		timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+		phase: "branch checkout fetch"
+	});
+	if (base.exitCode !== 0 || !changeRequestRef) return base;
+	return gitTransfer(sandbox, [
+		"-C",
+		workdir,
+		"fetch",
+		...pullRequestNumber !== void 0 ? ["--filter=blob:none"] : [],
+		"origin",
+		changeRequestRef
+	], {
+		env,
+		timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+		phase: "change request head fetch"
+	});
+}
+/** Check out a session's branch inside its isolated repository clone. */
+async function checkoutSessionBranch(sandbox, workdir, options) {
+	return timedPhase("workspace.checkout", () => checkoutSessionBranchImpl(sandbox, workdir, options));
+}
+/**
+* Bring a secondary environment repository onto the session branch at
+* session start. The primary repository keeps {@link checkoutSessionBranch};
+* every other repository follows a conservative rule: resume the session
+* branch when the remote or the local clone has it, otherwise create it from
+* the default branch tip (a detached HEAD, the template image pinned at its
+* build commit, is moved there first). A checkout that sits on any other
+* branch is left alone: it may carry local-only commits.
+*/
+async function syncEnvironmentRepository(sandbox, workdir, options) {
+	const { branch, defaultBranch, token, repoFullName, cloneUrl, authUsername } = options;
+	if (!isValidGitRef(branch) || !isValidGitRef(defaultBranch)) throw new MaterializeError("Refusing to sync a repository from an invalid branch name.", "pull-failed");
+	const authEnv = gitAuthenticationEnvironment(cloneUrl ?? cleanUrl(repoFullName), token, authUsername ?? "x-access-token", "pull-failed");
+	const current = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"branch",
+		"--show-current"
+	]);
+	if (current.exitCode !== 0) throw classifyGitFailure(current, "pull-failed");
+	const currentBranch = current.stdout.trim();
+	const kept = {
+		outcome: "kept",
+		branch: currentBranch || null
+	};
+	if (currentBranch === branch) return kept;
+	if ((await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"rev-parse",
+		"--verify",
+		"--quiet",
+		`refs/heads/${branch}`
+	])).exitCode === 0) {
+		const checkout = await execute(sandbox, "git", [
+			"-C",
+			workdir,
+			"checkout",
+			branch
+		], {
+			timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+			phase: "environment branch checkout"
+		});
+		if (checkout.exitCode === 0) return {
+			outcome: "resumed",
+			branch
+		};
+		if (isBlockedByLocalWork(checkout)) return kept;
+		throw classifyGitFailure(checkout, "pull-failed");
+	}
+	const remoteHeads = await gitTransfer(sandbox, [
+		"-C",
+		workdir,
+		"ls-remote",
+		"--heads",
+		"origin",
+		`refs/heads/${branch}`
+	], {
+		env: authEnv,
+		timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+		phase: "environment branch probe"
+	});
+	if (remoteHeads.exitCode !== 0) throw classifyGitFailure(remoteHeads, "pull-failed");
+	if (remoteHeads.stdout.trim()) {
+		const fetch = await gitTransfer(sandbox, [
+			"-C",
+			workdir,
+			"fetch",
+			"origin",
+			branch
+		], {
+			env: authEnv,
+			timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+			phase: "environment branch fetch"
+		});
+		if (fetch.exitCode !== 0) throw classifyGitFailure(fetch, "pull-failed");
+		const checkout = await execute(sandbox, "git", [
+			"-C",
+			workdir,
+			"checkout",
+			"-B",
+			branch,
+			"FETCH_HEAD"
+		], {
+			env: authEnv,
+			timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+			phase: "environment branch checkout"
+		});
+		if (checkout.exitCode === 0) return {
+			outcome: "resumed",
+			branch
+		};
+		if (isBlockedByLocalWork(checkout)) return kept;
+		throw classifyGitFailure(checkout, "pull-failed");
+	}
+	if (currentBranch && currentBranch !== defaultBranch) return kept;
+	if (currentBranch) {
+		const status = await execute(sandbox, "git", [
+			"-C",
+			workdir,
+			"status",
+			"--porcelain"
+		]);
+		if (status.exitCode !== 0) throw classifyGitFailure(status, "pull-failed");
+		if (status.stdout.trim()) return kept;
+	}
+	const fetch = await gitTransfer(sandbox, [
+		"-C",
+		workdir,
+		"fetch",
+		"origin",
+		defaultBranch
+	], {
+		env: authEnv,
+		timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+		phase: "environment default fetch"
+	});
+	if (fetch.exitCode !== 0) throw classifyGitFailure(fetch, "pull-failed");
+	if (currentBranch) {
+		const ancestor = await execute(sandbox, "git", [
+			"-C",
+			workdir,
+			"merge-base",
+			"--is-ancestor",
+			"HEAD",
+			"FETCH_HEAD"
+		]);
+		if (ancestor.exitCode === 1) return kept;
+		if (ancestor.exitCode !== 0) throw classifyGitFailure(ancestor, "pull-failed");
+	} else {
+		const checkout = await execute(sandbox, "git", [
+			"-C",
+			workdir,
+			"checkout",
+			"-B",
+			defaultBranch,
+			"FETCH_HEAD"
+		], {
+			env: authEnv,
+			timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+			phase: "environment default checkout"
+		});
+		if (checkout.exitCode !== 0) {
+			if (isBlockedByLocalWork(checkout)) return kept;
+			throw classifyGitFailure(checkout, "pull-failed");
+		}
+	}
+	const created = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"checkout",
+		"-b",
+		branch,
+		"FETCH_HEAD"
+	], {
+		timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+		phase: "environment branch create"
+	});
+	if (created.exitCode === 0) return {
+		outcome: "created",
+		branch
+	};
+	throw classifyGitFailure(created, "pull-failed");
+}
+/** Refresh an existing GitLab review checkout without exposing its credential to the agent. */
+async function refreshMergeRequestCheckout(sandbox, workdir, input) {
+	const { branch, mergeRequestNumber, expectedHeadSha, access } = input;
+	if (!isValidGitRef(branch) || !Number.isSafeInteger(mergeRequestNumber) || mergeRequestNumber <= 0 || !/^[0-9a-f]{40}$/i.test(expectedHeadSha)) throw new Error("Refusing to refresh a GitLab review with invalid session or head metadata.");
+	const token = access.authorization?.token;
+	if (!token) throw new Error("GitLab repository access did not include a bearer token.");
+	const env = gitAuthenticationEnvironment(access.cloneUrl, token, access.authorization?.username ?? "oauth2", "pull-failed");
+	const current = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"branch",
+		"--show-current"
+	]);
+	if (current.exitCode !== 0 || current.stdout.trim() !== branch) throw new Error("The active checkout is not on its bound review branch.");
+	const status = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"status",
+		"--porcelain",
+		"--untracked-files=all"
+	]);
+	if (status.exitCode !== 0 || status.stdout.trim()) throw new Error("The review checkout has local changes; refusing to replace them.");
+	const before = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"rev-parse",
+		"HEAD"
+	]);
+	if (before.exitCode !== 0) throw new Error("Could not read the current review checkout head.");
+	const fetch = await gitTransfer(sandbox, [
+		"-C",
+		workdir,
+		"fetch",
+		"origin",
+		`refs/merge-requests/${mergeRequestNumber}/head`
+	], {
+		env,
+		timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+		phase: "GitLab review head refresh"
+	});
+	if (fetch.exitCode !== 0) throw classifyGitFailure(fetch, "pull-failed");
+	const fetched = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"rev-parse",
+		"FETCH_HEAD"
+	]);
+	if (fetched.exitCode !== 0 || fetched.stdout.trim().toLowerCase() !== expectedHeadSha.toLowerCase()) throw new Error("The fetched GitLab review head differs from the provider-reported head; retry after it settles.");
+	if (before.stdout.trim().toLowerCase() === expectedHeadSha.toLowerCase()) return {
+		headSha: expectedHeadSha,
+		changed: false
+	};
+	const updated = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"checkout",
+		"-B",
+		branch,
+		"FETCH_HEAD"
+	], { env });
+	if (updated.exitCode !== 0) throw classifyGitFailure(updated, "pull-failed");
+	return {
+		headSha: expectedHeadSha,
+		changed: true
+	};
+}
+async function checkoutSessionBranchImpl(sandbox, workdir, options) {
+	const { branch, baseBranch, token, repoFullName, pullRequestNumber, mergeRequestNumber, cloneUrl, authUsername } = options;
+	if (!isValidGitRef(branch) || !isValidGitRef(baseBranch) || pullRequestNumber !== void 0 && mergeRequestNumber !== void 0 || mergeRequestNumber !== void 0 && (!Number.isSafeInteger(mergeRequestNumber) || mergeRequestNumber <= 0)) throw new MaterializeError("Refusing to create a session from an invalid branch name.", "clone-failed");
+	const changeRequestSession = pullRequestNumber !== void 0 || mergeRequestNumber !== void 0;
+	const cleanCloneUrl = cloneUrl ?? cleanUrl(repoFullName);
+	const authEnv = gitAuthenticationEnvironment(cleanCloneUrl, token, authUsername ?? "x-access-token", "pull-failed");
+	const credentialKey = authUsername ? "credential." + credentialScope(cleanCloneUrl) + ".helper" : "credential.helper";
+	if (authUsername) await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"config",
+		"--unset-all",
+		credentialKey
+	]);
+	else {
+		const configured = await execute(sandbox, "git", [
+			"-C",
+			workdir,
+			"config",
+			credentialKey,
+			GH_CREDENTIAL_HELPER
+		]);
+		if (configured.exitCode !== 0) throw classifyGitFailure(configured, "pull-failed");
+	}
+	const current = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"branch",
+		"--show-current"
+	]);
+	if (current.exitCode === 0 && current.stdout.trim() === branch) return;
+	if ((await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"show-ref",
+		"--verify",
+		"--quiet",
+		`refs/heads/${branch}`
+	])).exitCode === 0) {
+		const checkout = await execute(sandbox, "git", [
+			"-C",
+			workdir,
+			"checkout",
+			branch
+		], { env: authEnv });
+		if (checkout.exitCode !== 0) {
+			if (isBlockedByLocalWork(checkout)) return;
+			throw classifyGitFailure(checkout, "clone-failed");
+		}
+		return;
+	}
+	const fetch = await fetchStartPoint(sandbox, workdir, options, changeRequestSession && (await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"rev-parse",
+		"--is-shallow-repository"
+	])).stdout.trim() === "true", authEnv);
+	if (fetch.exitCode !== 0) throw classifyGitFailure(fetch, "pull-failed");
+	const create = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"checkout",
+		"-b",
+		branch,
+		"FETCH_HEAD"
+	], {
+		env: authEnv,
+		timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+		phase: "branch checkout"
+	});
+	if (create.exitCode === 0 || isBlockedByLocalWork(create)) return;
+	if (!isBranchCollision(create)) throw classifyGitFailure(create, "clone-failed");
+	const adopt = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"checkout",
+		branch
+	], { env: authEnv });
+	if (adopt.exitCode === 0 || isBlockedByLocalWork(adopt)) return;
+	let drop = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"update-ref",
+		"--no-deref",
+		"-d",
+		`refs/heads/${branch}`
+	]);
+	if (drop.exitCode !== 0) {
+		const gitDir = await execute(sandbox, "git", [
+			"-C",
+			workdir,
+			"rev-parse",
+			"--absolute-git-dir"
+		]);
+		if (gitDir.exitCode !== 0 || !gitDir.stdout.trim()) throw classifyGitFailure(create, "clone-failed");
+		drop = await execute(sandbox, "rm", [
+			"-f",
+			"--",
+			`${gitDir.stdout.trim()}/refs/heads/${branch}`
+		]);
+	}
+	if (drop.exitCode !== 0) throw classifyGitFailure(create, "clone-failed");
+	const retry = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"checkout",
+		"-b",
+		branch,
+		"FETCH_HEAD"
+	], {
+		env: authEnv,
+		timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
+		phase: "branch checkout retry"
+	});
+	if (retry.exitCode !== 0) {
+		if (isBlockedByLocalWork(retry)) return;
+		throw classifyGitFailure(retry, "clone-failed");
+	}
+}
+/**
+* True when `git checkout -b` failed only because the branch ref already
+* exists — the collision Factory hits when a pooled sandbox carries a ref the
+* show-ref probe could not see (broken loose ref) or a concurrent
+* materialization created the branch after the probe ran.
+*/
+function isBranchCollision(result) {
+	return /a branch named .* already exists/i.test(`${result.stderr || ""}\n${result.stdout || ""}`);
+}
+/**
+* True when a failed `git checkout` just means uncommitted or untracked files
+* in the working tree would be clobbered by the branch switch. Those files are
+* a session's work in progress — the switch must yield to them, never the
+* other way around.
+*/
+function isBlockedByLocalWork(result) {
+	const output = `${result.stderr || ""}\n${result.stdout || ""}`;
+	return /Your local changes to the following files would be overwritten by checkout|untracked working tree files would be overwritten by checkout/i.test(output);
+}
+/**
+* Return the origin URL when the workdir contains this repository, including a
+* legacy checkout whose remote still embeds credentials.
+*/
+async function existingCheckoutRemote(sandbox, workdir, cloneUrl) {
+	const result = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"remote",
+		"get-url",
+		"origin"
+	]);
+	if (result.exitCode !== 0) return null;
+	const url = result.stdout.trim();
+	const actual = normalizedRemoteUrl(url);
+	const expected = normalizedRemoteUrl(cloneUrl);
+	return actual !== null && expected !== null && actual === expected ? url : null;
+}
+/** Remove credentials persisted by an older implementation from origin. */
+async function scrubRemote(sandbox, workdir, repoFullName, cloneUrl = cleanUrl(repoFullName)) {
+	let failure;
+	try {
+		const result = await execute(sandbox, "git", [
+			"-C",
+			workdir,
+			"remote",
+			"set-url",
+			"origin",
+			cloneUrl
+		]);
+		if (result.exitCode === 0) return;
+		failure = result.stderr.trim() || result.stdout.trim();
+	} catch (error) {
+		failure = error instanceof Error ? error.message : String(error);
+	}
+	throw new MaterializeError(`Failed to scrub installation token from git remote: ${failure}`, "pull-failed");
+}
+/**
+* Turn a failed git command into an actionable error, detecting the common
+* "cannot reach github.com" egress failure.
+*/
+function classifyGitFailure(result, fallback) {
+	const stderr = result.stderr || "";
+	if (/could not resolve host|failed to connect|network is unreachable|Connection timed out/i.test(stderr)) return new MaterializeError("The sandbox could not reach github.com. The sandbox network must allow outbound egress to github.com.", "egress-blocked");
+	return new MaterializeError(`git ${fallback === "clone-failed" ? "clone" : fallback === "pull-failed" ? "pull" : "push"} failed: ${stderr}`, fallback);
+}
+/**
+* Resolve a concrete `{ name, email }` for git authorship from a possibly-sparse
+* identity. Falls back to a GitHub-style noreply identity so commits are never
+* authored with an empty or host-derived identity.
+*/
+function resolveGitIdentity(identity) {
+	const login = (identity.login || "").trim();
+	return {
+		name: (identity.name || "").trim() || login || "Mastra Code",
+		email: (identity.email || "").trim() || (login ? `${login}@users.noreply.github.com` : "mastra-code@users.noreply.github.com")
+	};
+}
+/** Configure repository-local commit identity through direct Git argv calls. */
+async function configureGitIdentity(sandbox, workdir, identity) {
+	const { name, email } = resolveGitIdentity(identity);
+	const setName = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"config",
+		"user.name",
+		name
+	]);
+	if (setName.exitCode !== 0) throw new MaterializeError(`Failed to set git user.name: ${setName.stderr.trim()}`, "commit-failed");
+	const setEmail = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"config",
+		"user.email",
+		email
+	]);
+	if (setEmail.exitCode !== 0) throw new MaterializeError(`Failed to set git user.email: ${setEmail.stderr.trim()}`, "commit-failed");
+}
+async function pushAuthenticatedBranch(sandbox, workdir, branch, cloneUrl, token, username) {
+	const env = gitAuthenticationEnvironment(cloneUrl, token, username, "push-failed");
+	const push = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"push",
+		"-u",
+		"origin",
+		branch
+	], { env });
+	if (push.exitCode !== 0) throw classifyGitFailure(push, "push-failed");
+}
+/** Whether the checkout has a local `refs/heads/<branch>`. */
+async function hasLocalBranch(sandbox, workdir, branch) {
+	const ref = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"show-ref",
+		"--verify",
+		"--quiet",
+		`refs/heads/${branch}`
+	]);
+	if (ref.exitCode === 0) return true;
+	if (ref.exitCode === 1) return false;
+	throw classifyGitFailure(ref, "push-failed");
+}
+/**
+* Make sure the checkout has a local `<branch>`. Where it was never created,
+* create it at `HEAD` and switch to it, so the agent's next commits land on
+* the branch every push sends; the index and working tree carry over.
+*/
+async function ensureLocalBranch(sandbox, workdir, branch) {
+	if (await hasLocalBranch(sandbox, workdir, branch)) return;
+	const created = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"switch",
+		"-c",
+		branch
+	]);
+	if (created.exitCode !== 0) throw classifyGitFailure(created, "push-failed");
+}
+/** Whether `workdir` is a checkout of the repository at `cloneUrl`. */
+async function isCheckoutOf(sandbox, workdir, cloneUrl) {
+	return await existingCheckoutRemote(sandbox, workdir, cloneUrl) !== null;
+}
+/**
+* Push a branch back to GitHub with credentials scoped to the Git process.
+* The token never enters argv, a repository URL, or persistent configuration.
+*/
+async function pushBranch(sandbox, workdir, branch, token, repoFullName) {
+	if (!isValidGitRef(branch)) throw new MaterializeError(`Refusing to push: invalid branch name '${branch}'.`, "push-failed");
+	if (!/^[\w.-]+(?:\/[\w.-]+)+$/.test(repoFullName)) throw new MaterializeError(`Refusing to push: invalid repo full name '${repoFullName}'.`, "push-failed");
+	await pushAuthenticatedBranch(sandbox, workdir, branch, cleanUrl(repoFullName), token, "x-access-token");
+}
+/**
+* Push the active session branch through the provider-neutral repository
+* access contract without persisting or exposing provider credentials.
+*/
+async function pushRepositoryBranch(sandbox, workdir, branch, access, repoFullName) {
+	if (!isValidGitRef(branch)) throw new MaterializeError(`Refusing to push: invalid branch name '${branch}'.`, "push-failed");
+	if (!/^[\w.-]+(?:\/[\w.-]+)+$/.test(repoFullName)) throw new MaterializeError(`Refusing to push: invalid repo full name '${repoFullName}'.`, "push-failed");
+	const authorization = access.authorization;
+	if (!authorization?.token) throw new MaterializeError("Repository access did not include push credentials.", "push-failed");
+	await pushAuthenticatedBranch(sandbox, workdir, branch, access.cloneUrl, authorization.token, authorization.username ?? "x-access-token");
+}
+/**
+* Stage every change in the working tree and create a commit inside the
+* sandbox. The git identity is configured first so authorship is correct. When
+* there is nothing to commit this is a no-op (`committed: false`) rather than an
+* error, so callers can safely commit-then-push without first diffing.
+*
+* @param sandbox  the live sandbox containing the checkout
+* @param workdir  the session workdir to commit in
+* @param message  the commit message (passed as one argv value)
+* @param identity authorship identity for the commit
+*/
+async function commitAll(sandbox, workdir, message, identity) {
+	await configureGitIdentity(sandbox, workdir, identity);
+	const add = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"add",
+		"-A"
+	]);
+	if (add.exitCode !== 0) throw new MaterializeError(`git add failed: ${add.stderr.trim() || add.stdout.trim()}`, "commit-failed");
+	if ((await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"diff",
+		"--cached",
+		"--quiet"
+	])).exitCode === 0) return { committed: false };
+	const commit = await execute(sandbox, "git", [
+		"-C",
+		workdir,
+		"commit",
+		"-m",
+		message
+	]);
+	if (commit.exitCode !== 0) throw new MaterializeError(`git commit failed: ${commit.stderr.trim() || commit.stdout.trim()}`, "commit-failed");
+	return { committed: true };
+}
+/** Error raised when the org's setup or teardown command fails in the sandbox. */
+var SetupCommandError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "SetupCommandError";
+	}
+};
+/**
+* Run the project's setup command (e.g. `pnpm i && pnpm build`) inside the
+* freshly materialized session workdir. Called before the checkout is handed
+* to any agent run so it is ready to build/test. A non-zero exit is a hard
+* error — starting agent work in a half-set-up tree is worse than failing the
+* request.
+*
+* Security model: the command is intentionally arbitrary shell — that is the
+* feature (install deps, build, seed fixtures). It is only configurable by
+* authenticated org members (the settings route is gated by
+* `resolveOrgTenant` + org-scoped project lookup, with length and
+* control-character validation), and it executes exclusively inside the
+* project's isolated sandbox — the same environment where org members already
+* run arbitrary shell via the agent's command tool. It never runs on the web
+* server host, so it grants no privilege beyond what sandbox access already
+* provides.
+*
+* @param sandbox  live sandbox containing the checkout
+* @param workdir  the server-resolved session workdir the command runs in
+* @param command  the org-configured setup shell command
+*/
+async function runLifecycleCommand(sandbox, workdir, command, options) {
+	const result = await sh(sandbox, `cd ${shellQuote(workdir)} && { ${command}\n}`, {
+		phase: `${options.phase} command`,
+		...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {}
+	});
+	if (result.exitCode !== 0) {
+		const detail = (result.stderr.trim() || result.stdout.trim()).slice(-1800);
+		throw new SetupCommandError(`${options.phase === "setup" ? "Setup" : "Teardown"} command failed (exit ${result.exitCode}): ${detail}`, options.phase === "setup" ? "setup-failed" : "teardown-failed");
+	}
+}
+async function runSetupCommand(sandbox, workdir, command) {
+	return runLifecycleCommand(sandbox, workdir, command, { phase: "setup" });
+}
+/**
+* Run the repository's best-effort teardown command from the materialized
+* session workdir. Callers own lifecycle policy: this helper reports failures
+* so the retirement coordinator can log them while still continuing with
+* scrub, pooling/destruction, cache invalidation, and row deletion.
+*/
+async function runTeardownCommand(sandbox, workdir, command, options = {}) {
+	return runLifecycleCommand(sandbox, workdir, command, {
+		phase: "teardown",
+		...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {}
+	});
+}
+/**
+* Preflight that `gh` is installed in the sandbox. Only called on the PR path so
+* a missing `gh` never blocks clone/open. Surfaces an actionable error naming
+* the sandbox template requirement.
+*/
+async function assertGhAvailable(sandbox) {
+	if ((await execute(sandbox, "gh", ["--version"])).exitCode !== 0) throw new MaterializeError("The GitHub CLI (gh) is not installed in the sandbox. The sandbox template must include gh to open pull requests.", "gh-missing");
+}
+/** Match the first GitHub PR URL in `gh pr create` output. */
+function parsePullRequestUrl(stdout) {
+	return stdout.match(/https:\/\/github\.com\/[^\s]+\/pull\/\d+/)?.[0];
+}
+/**
+* Open a pull request from inside the sandbox via `gh pr create`. The token is
+* passed only through a per-invocation `GH_TOKEN` env scoped to the single `gh`
+* process (never persisted), all arguments are passed as structured argv, and
+* the resulting PR URL is parsed from stdout.
+*
+* @param sandbox live sandbox containing the checkout
+* @param workdir the worktree (or repo) path the PR head branch is checked out in
+*/
+async function createPullRequest(sandbox, workdir, { token, base, head, title, body }) {
+	if (!isValidGitRef(base)) throw new MaterializeError(`Refusing to open PR: invalid base branch '${base}'.`, "pr-failed");
+	if (!isValidGitRef(head)) throw new MaterializeError(`Refusing to open PR: invalid head branch '${head}'.`, "pr-failed");
+	await assertGhAvailable(sandbox);
+	const result = await execute(sandbox, "gh", [
+		"pr",
+		"create",
+		"--base",
+		base,
+		"--head",
+		head,
+		"--title",
+		title,
+		"--body",
+		body ?? ""
+	], {
+		cwd: workdir,
+		env: { GH_TOKEN: token }
+	});
+	if (result.exitCode !== 0) {
+		const classified = classifyGitFailure(result, "push-failed");
+		if (classified.code === "egress-blocked") throw classified;
+		throw new MaterializeError(`gh pr create failed: ${result.stderr.trim() || result.stdout.trim()}`, "pr-failed");
+	}
+	const url = parsePullRequestUrl(result.stdout);
+	if (!url) throw new MaterializeError(`gh pr create succeeded but no PR URL was found in its output: ${result.stdout.trim()}`, "pr-failed");
+	return { url };
+}
+//#endregion
+export { CHECKOUT_COMMAND_TIMEOUT_MS, DEFAULT_COMMAND_TIMEOUT_MS, MaterializeError, SetupCommandError, checkoutSessionBranch, commitAll, configureGitIdentity, createPullRequest, ensureLocalBranch, hasLocalBranch, isCheckoutOf, isValidGitRef, materializeRepo, pushBranch, pushRepositoryBranch, refreshMergeRequestCheckout, resolveGitIdentity, runSetupCommand, runTeardownCommand, sh, shellQuote, syncEnvironmentRepository };
+
+//# sourceMappingURL=sandbox.js.map