@mastra/factory 0.16.0-alpha.9 → 0.16.0

package/dist/integrations/github/sandbox.js

@@ -1,23 +1,7 @@
 import { timedPhase } from "../../timing.js";
-import { repoCloneCommand } from "../../packages/_internals/workspace/dist/index.js";
+import { isValidGitRef } from "../../sandbox/git-ref.js";
 //#region src/integrations/github/sandbox.ts
 /**
-* Repo materialization for GitHub-backed repositories.
-*
-* A GitHub repo is never cloned onto the server host. The repo is cloned
-* *inside* the session's sandbox, so the agent's file tools and command tools
-* operate entirely against the remote checkout.
-*
-* - `materializeRepo(row, token)` clones the repo inside the sandbox when no
-*   checkout exists yet (a base-image boot, a wiped disk), using a short-lived
-*   installation token that is scrubbed from the git remote afterwards so it
-*   never persists in the VM. A checkout that is already there, from a repo
-*   template image or an earlier start, is left exactly as it is.
-*
-* This module owns everything git/GitHub: clone, commit/push, setup/teardown commands,
-* and `gh pr create`. Workdir layout lives in `../sandbox/workdir`.
-*/
-/**
 * 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
@@ -38,6 +22,7 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 15 * 6e4;
 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
@@ -51,18 +36,24 @@ function isTransientTransportError(error) {
 const SH_RETRIES = 2;
 const SH_RETRY_DELAY_MS = 2e3;
 /**
-* Run a shell script in the sandbox via `sh -c`, bounded by a hang guard.
-* Transient transport-level 5xx failures (proxy hiccups while the VM boots)
-* are retried with a short backoff; every script routed through here is safe
-* to re-run. Hang-guard timeouts are NOT retried — the budget applies to the
-* command as a whole.
+* 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 shOnce(sandbox, script, {
+			const result = await executeOnce(sandbox, command, args, {
 				...options,
 				timeoutMs: Math.max(deadlineMs - Date.now(), 1)
 			});
@@ -77,8 +68,8 @@ async function sh(sandbox, script, options = {}) {
 		}
 	}
 }
-/** Single `sh -c` execution attempt, bounded by the hang guard. */
-async function shOnce(sandbox, script, options) {
+/** 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) => {
@@ -89,7 +80,11 @@ async function shOnce(sandbox, script, options) {
 		timer.unref?.();
 	});
 	try {
-		return await Promise.race([sandbox.executeCommand("sh", ["-c", script], { timeout: timeoutMs }), hangGuard]);
+		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);
 	}
@@ -123,16 +118,16 @@ function isTransientGitFailure(result) {
 * `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, script, options = {}) {
-	const { beforeRetry, ...shOptions } = options;
-	const deadlineMs = Date.now() + (shOptions.timeoutMs ?? 9e5);
+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 sh(sandbox, script, {
-			...shOptions,
+		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 ${shOptions.phase ?? "transfer"} retrying after attempt ${attempt + 1}\n`);
+		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));
@@ -148,21 +143,72 @@ var MaterializeError = class extends Error {
 		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;
+}
 /**
-* Build the token-auth clone/pull URL for a repo. The token lives only inside
-* this URL and is scrubbed from the remote after the operation.
+* 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 tokenUrl(repoFullName, token) {
-	return `https://x-access-token:${token}@github.com/${repoFullName}.git`;
+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");
+	return {
+		GIT_CONFIG_COUNT: "1",
+		GIT_CONFIG_KEY_0: `http.${scope}.extraHeader`,
+		GIT_CONFIG_VALUE_0: `Authorization: Basic ${authorization}`,
+		GIT_TERMINAL_PROMPT: "0"
+	};
 }
-function cleanUrl(repoFullName) {
-	return `https://github.com/${repoFullName}.git`;
+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. Scrubs the install token from the
-* remote after a clone and sets `materialized_at` on the per-user sandbox
-* binding row.
+* 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));
@@ -171,35 +217,33 @@ 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 (!/^[\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 sh(sandbox, "git --version")).exitCode !== 0) throw new MaterializeError("git is not installed in the sandbox. The sandbox template must include git.", "git-missing");
-	const existing = await existingCheckoutRemote(sandbox, workdir, repo);
+	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, true);
+		if (/\/\/[^/]*@/.test(existing)) await scrubRemote(sandbox, workdir, repo, cleanCloneUrl);
 	} else {
-		await sh(sandbox, `mkdir -p ${shellQuote(workdir)} && find ${shellQuote(workdir)} -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +`);
-		let tokenInRemote = false;
-		try {
-			const clone = await gitTransfer(sandbox, repoCloneCommand({
-				cloneUrl: tokenUrl(repo, token),
-				destination: workdir,
-				branch: repoInfo.defaultBranch
-			}), {
-				phase: "repository clone",
-				beforeRetry: async () => {
-					await sh(sandbox, `mkdir -p ${shellQuote(workdir)} && find ${shellQuote(workdir)} -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +`);
-				}
-			});
-			if (clone.exitCode !== 0) {
-				tokenInRemote = await hasGitDir(sandbox, workdir);
-				throw classifyGitFailure(clone, "clone-failed");
+		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);
 			}
-			tokenInRemote = true;
-		} catch (primary) {
-			throw await scrubbedFailure(sandbox, workdir, repo, tokenInRemote, primary, "clone-failed");
-		}
-		await scrubRemote(sandbox, workdir, repo, tokenInRemote);
+		});
+		if (clone.exitCode !== 0) throw classifyGitFailure(clone, "clone-failed");
 	}
 	await storage.markMaterialized({ id: sandboxRow.id });
 }
@@ -208,61 +252,222 @@ async function materializeRepoImpl(options) {
 * answers from the session's `GH_TOKEN`, so no credential is ever written.
 */
 const GH_CREDENTIAL_HELPER = "!gh auth git-credential";
-/**
-* A pull-request session first fetches the base's whole commit history without
-* file contents, so `git log` and `git blame` work in the review, then the PR
-* head. Every other session starts from the shallow base tip as it is.
-*/
-function startPointFetchCommands(workdir, { baseBranch, pullRequestNumber }, shallowClone) {
-	const git = `git -C ${shellQuote(workdir)}`;
-	if (pullRequestNumber === void 0) return `${git} fetch origin ${shellQuote(baseBranch)}`;
-	return `${git} fetch ${shallowClone ? "--unshallow " : ""}--filter=blob:none origin ${shellQuote(baseBranch)} && ${git} fetch --filter=blob:none origin refs/pull/${pullRequestNumber}/head`;
+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));
 }
+/** 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 } = options;
-	if (!isValidGitRef(branch) || !isValidGitRef(baseBranch)) throw new MaterializeError("Refusing to create a session from an invalid branch name.", "clone-failed");
-	const pullRequestSession = pullRequestNumber !== void 0;
-	await sh(sandbox, `git -C ${shellQuote(workdir)} config credential.helper ${shellQuote(GH_CREDENTIAL_HELPER)}`);
-	const current = await sh(sandbox, `git -C ${shellQuote(workdir)} branch --show-current`);
+	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 sh(sandbox, `git -C ${shellQuote(workdir)} show-ref --verify --quiet refs/heads/${shellQuote(branch)}`)).exitCode === 0) {
-		const checkout = await sh(sandbox, `git -C ${shellQuote(workdir)} checkout ${shellQuote(branch)}`);
+	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 shallowClone = pullRequestSession && (await sh(sandbox, `git -C ${shellQuote(workdir)} rev-parse --is-shallow-repository`)).stdout.trim() === "true";
-	const authUrl = tokenUrl(repoFullName, token);
-	try {
-		const setUrl = await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(authUrl)}`, { phase: "branch checkout remote" });
-		if (setUrl.exitCode !== 0) throw classifyGitFailure(setUrl, "pull-failed");
-		const fetch = await sh(sandbox, `${startPointFetchCommands(workdir, options, shallowClone)} && git -C ${shellQuote(workdir)} checkout -b ${shellQuote(branch)} FETCH_HEAD`, {
-			timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
-			phase: "branch checkout"
-		});
-		if (fetch.exitCode !== 0) {
-			if (isBlockedByLocalWork(fetch)) return;
-			if (!isBranchCollision(fetch)) throw classifyGitFailure(fetch, "clone-failed");
-			const adopt = await sh(sandbox, `git -C ${shellQuote(workdir)} checkout ${shellQuote(branch)}`);
-			if (adopt.exitCode === 0 || isBlockedByLocalWork(adopt)) return;
-			if ((await sh(sandbox, `git -C ${shellQuote(workdir)} update-ref --no-deref -d refs/heads/${shellQuote(branch)} || rm -f -- "$(git -C ${shellQuote(workdir)} rev-parse --absolute-git-dir)/refs/heads/${branch}"`)).exitCode !== 0) throw classifyGitFailure(fetch, "clone-failed");
-			const retry = await sh(sandbox, `git -C ${shellQuote(workdir)} checkout -b ${shellQuote(branch)} FETCH_HEAD`, {
-				timeoutMs: CHECKOUT_COMMAND_TIMEOUT_MS,
-				phase: "branch checkout retry"
-			});
-			if (retry.exitCode !== 0) {
-				if (isBlockedByLocalWork(retry)) return;
-				throw classifyGitFailure(retry, "clone-failed");
-			}
-		}
-	} finally {
-		await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(cleanUrl(repoFullName))}`);
+	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");
 	}
 }
 /**
@@ -285,50 +490,35 @@ function isBlockedByLocalWork(result) {
 	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);
 }
 /**
-* The `origin` URL of a checkout of this exact repo in the workdir, or null
-* when there is none. Matches both the clean and token-auth URL forms; any
-* other remote (or no git dir at all) sends materialize down the clone path.
+* Return the origin URL when the workdir contains this repository, including a
+* legacy checkout whose remote still embeds credentials.
 */
-async function existingCheckoutRemote(sandbox, workdir, repoFullName) {
-	const result = await sh(sandbox, `git -C ${shellQuote(workdir)} remote get-url origin`);
+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();
-	return isRemoteForRepo(url, repoFullName) ? url : null;
+	const actual = normalizedRemoteUrl(url);
+	const expected = normalizedRemoteUrl(cloneUrl);
+	return actual !== null && expected !== null && actual === expected ? url : null;
 }
-/** True only for `https://github.com/<repo>[.git]`, with or without embedded credentials. */
-function isRemoteForRepo(url, repoFullName) {
-	let parsed;
-	try {
-		parsed = new URL(url);
-	} catch {
-		return false;
-	}
-	if (parsed.protocol !== "https:" || parsed.hostname.toLowerCase() !== "github.com") return false;
-	if (parsed.port !== "" || parsed.search !== "" || parsed.hash !== "") return false;
-	return parsed.pathname.replace(/\.git$/, "").toLowerCase() === `/${repoFullName.toLowerCase()}`;
-}
-/** Probed without `git -C` so a missing workdir returns false instead of throwing. */
-async function hasGitDir(sandbox, workdir) {
-	return (await sh(sandbox, `test -d ${shellQuote(`${workdir}/.git`)}`).catch(() => null))?.exitCode === 0;
-}
-/**
-* Reset the git remote back to the tokenless URL. Strict when the token
-* reached the remote: any failure — a non-zero exit or a provider throw —
-* means the token may still be persisted, so it is thrown for the caller to
-* surface. Best-effort when it never did: the workdir may not exist (e.g. a
-* failed clone), which makes providers that spawn with `cwd` throw rather
-* than return a non-zero exit code; both outcomes are tolerated so neither
-* masks the primary failure.
-*/
-async function scrubRemote(sandbox, workdir, repoFullName, tokenInRemote) {
-	const scrub = `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(cleanUrl(repoFullName))}`;
-	if (!tokenInRemote) {
-		await sh(sandbox, scrub).catch(() => void 0);
-		return;
-	}
+/** Remove credentials persisted by an older implementation from origin. */
+async function scrubRemote(sandbox, workdir, repoFullName, cloneUrl = cleanUrl(repoFullName)) {
 	let failure;
 	try {
-		const result = await sh(sandbox, scrub);
+		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) {
@@ -337,23 +527,6 @@ async function scrubRemote(sandbox, workdir, repoFullName, tokenInRemote) {
 	throw new MaterializeError(`Failed to scrub installation token from git remote: ${failure}`, "pull-failed");
 }
 /**
-* Scrub after `primary` already failed and return the error to throw. A failed
-* scrub is appended to `primary` rather than replacing it, so the caller gets
-* the error it would have had without the scrub — same class, same `code` —
-* carrying the leaked-token warning in its message.
-*/
-async function scrubbedFailure(sandbox, workdir, repoFullName, tokenInRemote, primary, fallback) {
-	try {
-		await scrubRemote(sandbox, workdir, repoFullName, tokenInRemote);
-		return primary;
-	} catch (scrubError) {
-		const scrubMessage = scrubError instanceof Error ? scrubError.message : String(scrubError);
-		if (!(primary instanceof Error)) return new MaterializeError(`${String(primary)} — additionally: ${scrubMessage}`, fallback);
-		primary.message = `${primary.message} — additionally: ${scrubMessage}`;
-		return primary;
-	}
-}
-/**
 * Turn a failed git command into an actionable error, detecting the common
 * "cannot reach github.com" egress failure.
 */
@@ -363,14 +536,6 @@ function classifyGitFailure(result, fallback) {
 	return new MaterializeError(`git ${fallback === "clone-failed" ? "clone" : fallback === "pull-failed" ? "pull" : "push"} failed: ${stderr}`, fallback);
 }
 /**
-* Validate a git ref (branch) name. Server-side defense-in-depth: only allow a
-* conservative character set so a branch can never be built into a shell
-* command in a way that escapes quoting. Mirrors the route-layer check.
-*/
-function isValidGitRef(value) {
-	return typeof value === "string" && value.length > 0 && value.length <= 255 && !value.startsWith("-") && /^[A-Za-z0-9_./-]+$/.test(value);
-}
-/**
 * 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.
@@ -382,57 +547,57 @@ function resolveGitIdentity(identity) {
 		email: (identity.email || "").trim() || (login ? `${login}@users.noreply.github.com` : "mastra-code@users.noreply.github.com")
 	};
 }
-/**
-* Configure `user.name` / `user.email` for the given repo working tree inside
-* the sandbox so commits are authored correctly. Values are shell-quoted.
-*/
+/** Configure repository-local commit identity through direct Git argv calls. */
 async function configureGitIdentity(sandbox, workdir, identity) {
 	const { name, email } = resolveGitIdentity(identity);
-	const setName = await sh(sandbox, `git -C ${shellQuote(workdir)} config user.name ${shellQuote(name)}`);
+	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 sh(sandbox, `git -C ${shellQuote(workdir)} config user.email ${shellQuote(email)}`);
+	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");
+}
 /**
-* Temporarily rewrite `origin` to a tokenized URL, run `fn` (e.g. a push), and
-* **always** scrub the remote back to the tokenless URL afterwards. The token
-* therefore only ever lives in the remote URL for the duration of the
-* operation and is never left in the VM's git config.
-*
-* Once the tokenized URL is installed a failed scrub may leave the token
-* persisted, so it is always surfaced: on its own after a successful `fn`,
-* appended to `fn`'s own error otherwise — `fn`'s error is never replaced.
-* Only a failed set-url (the token never reached the remote) downgrades the
-* scrub to best-effort.
+* 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 withInstallToken(sandbox, workdir, repoFullName, token, fn) {
-	if (!/^[\w.-]+\/[\w.-]+$/.test(repoFullName)) throw new MaterializeError(`Refusing to push: invalid repo full name '${repoFullName}'.`, "push-failed");
-	const setUrl = await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(tokenUrl(repoFullName, token))}`);
-	if (setUrl.exitCode !== 0) {
-		await scrubRemote(sandbox, workdir, repoFullName, false);
-		throw new MaterializeError(`Failed to set git remote: ${setUrl.stderr.trim()}`, "push-failed");
-	}
-	let result;
-	try {
-		result = await fn();
-	} catch (primary) {
-		throw await scrubbedFailure(sandbox, workdir, repoFullName, true, primary, "push-failed");
-	}
-	await scrubRemote(sandbox, workdir, repoFullName, true);
-	return result;
+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 a branch back to GitHub from inside the sandbox using a short-lived
-* installation token. The branch is ref-validated, the token is injected only
-* into the remote URL via `withInstallToken`, and egress failures are
-* classified into actionable errors.
+* Push the active session branch through the provider-neutral repository
+* access contract without persisting or exposing provider credentials.
 */
-async function pushBranch(sandbox, workdir, branch, token, repoFullName) {
+async function pushRepositoryBranch(sandbox, workdir, branch, access, repoFullName) {
 	if (!isValidGitRef(branch)) throw new MaterializeError(`Refusing to push: invalid branch name '${branch}'.`, "push-failed");
-	await withInstallToken(sandbox, workdir, repoFullName, token, async () => {
-		const push = await sh(sandbox, `git -C ${shellQuote(workdir)} push -u origin ${shellQuote(branch)}`);
-		if (push.exitCode !== 0) throw classifyGitFailure(push, "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
@@ -442,15 +607,32 @@ async function pushBranch(sandbox, workdir, branch, token, repoFullName) {
 *
 * @param sandbox  the live sandbox containing the checkout
 * @param workdir  the session workdir to commit in
-* @param message  the commit message (quoted; arbitrary text is safe)
+* @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 sh(sandbox, `git -C ${shellQuote(workdir)} add -A`);
+	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 sh(sandbox, `git -C ${shellQuote(workdir)} diff --cached --quiet`)).exitCode === 0) return { committed: false };
-	const commit = await sh(sandbox, `git -C ${shellQuote(workdir)} commit -m ${shellQuote(message)}`);
+	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 };
 }
@@ -515,7 +697,7 @@ async function runTeardownCommand(sandbox, workdir, command, options = {}) {
 * the sandbox template requirement.
 */
 async function assertGhAvailable(sandbox) {
-	if ((await sh(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");
+	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) {
@@ -524,8 +706,8 @@ function parsePullRequestUrl(stdout) {
 /**
 * 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 shell-quoted, and the resulting
-* PR URL is parsed from stdout.
+* 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
@@ -534,14 +716,21 @@ async function createPullRequest(sandbox, workdir, { token, base, head, title, b
 	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 ghCommand = [
-		`GH_TOKEN=${shellQuote(token)} gh pr create`,
-		`--base ${shellQuote(base)}`,
-		`--head ${shellQuote(head)}`,
-		`--title ${shellQuote(title)}`,
-		`--body ${shellQuote(body ?? "")}`
-	].join(" ");
-	const result = await sh(sandbox, `cd ${shellQuote(workdir)} && ${ghCommand}`);
+	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;
@@ -552,6 +741,6 @@ async function createPullRequest(sandbox, workdir, { token, base, head, title, b
 	return { url };
 }
 //#endregion
-export { CHECKOUT_COMMAND_TIMEOUT_MS, DEFAULT_COMMAND_TIMEOUT_MS, MaterializeError, SetupCommandError, checkoutSessionBranch, commitAll, configureGitIdentity, createPullRequest, isValidGitRef, materializeRepo, pushBranch, resolveGitIdentity, runSetupCommand, runTeardownCommand, sh, shellQuote, withInstallToken };
+export { CHECKOUT_COMMAND_TIMEOUT_MS, DEFAULT_COMMAND_TIMEOUT_MS, MaterializeError, SetupCommandError, checkoutSessionBranch, commitAll, configureGitIdentity, createPullRequest, isValidGitRef, materializeRepo, pushBranch, pushRepositoryBranch, refreshMergeRequestCheckout, resolveGitIdentity, runSetupCommand, runTeardownCommand, sh, shellQuote };
 
 //# sourceMappingURL=sandbox.js.map