@mastra/factory 0.0.0-fix-thread-subscription-multi-instance-redis-streams-20260730204150

package/dist/integrations/github/sandbox.js

@@ -0,0 +1,547 @@
+import { reportProgress } from "../../sandbox/fleet.js";
+import { createHash } from "crypto";
+//#region src/integrations/github/sandbox.ts
+/**
+* Repo materialization for GitHub-backed repositories.
+*
+* A GitHub repo is never cloned onto the server host. Instead each project gets
+* its own isolated sandbox (provisioned by the fleet in `../sandbox/fleet`) and
+* the repo is cloned *inside* that sandbox. The agent's file tools and command
+* tools then operate entirely against the remote checkout.
+*
+* - `ensureProjectSandbox(row)` / `teardownProjectSandbox(row)` bind the fleet's
+*   provision/reattach/teardown lifecycle to the per-(project,user) sandbox row.
+* - `materializeRepo(row, token)` runs `git clone` (first open) or `git pull`
+*   (re-open) inside the sandbox, using a short-lived installation token that is
+*   scrubbed from the git remote afterwards so it never persists in the VM.
+*
+* This module owns everything git/GitHub: clone/pull, commit/push, worktrees,
+* and `gh pr create`. Sandbox provisioning, budgets, and workdir layout live in
+* the fleet module.
+*/
+/** Adapt a per-(project,user) sandbox binding row to the fleet's persistence seam. */
+function bindingStore(row, storage) {
+	return {
+		sandboxId: row.sandboxId,
+		setSandboxId: (id) => id === null ? storage.clearBinding({ id: row.id }) : storage.setSandboxId({
+			id: row.id,
+			sandboxId: id
+		}),
+		clear: () => storage.clearBinding({ id: row.id })
+	};
+}
+/**
+* Provision a new sandbox (persisting its provider id on first open) or
+* reattach to the stored one. Returns a started, live sandbox.
+*/
+async function ensureProjectSandbox(options) {
+	const { fleet, row, storage, token, onProgress } = options;
+	return fleet.ensureSandbox(bindingStore(row, storage), { GH_TOKEN: token }, onProgress);
+}
+/**
+* Tear down a user's sandbox for a project: stop the live VM (best-effort) and
+* clear the persisted `sandboxId`/`materializedAt` on the per-(project,user)
+* binding row so the next open re-provisions cleanly.
+*
+* @param row     the per-(project,user) sandbox binding to tear down
+* @param sandbox an already-reattached live sandbox to stop, when available
+*/
+async function teardownProjectSandbox(options) {
+	const { fleet, row, storage, sandbox } = options;
+	return fleet.teardownSandbox(bindingStore(row, storage), sandbox);
+}
+/**
+* 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`, 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.
+*/
+async function sh(sandbox, script, options = {}) {
+	const deadlineMs = Date.now() + (options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS);
+	for (let attempt = 0;; attempt++) try {
+		return await shOnce(sandbox, script, {
+			...options,
+			timeoutMs: Math.max(deadlineMs - Date.now(), 1)
+		});
+	} catch (error) {
+		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 `sh -c` execution attempt, bounded by the hang guard. */
+async function shOnce(sandbox, script, options) {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+	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("sh", ["-c", script], { timeout: timeoutMs }), hangGuard]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** 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";
+	}
+};
+/**
+* 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.
+*/
+function tokenUrl(repoFullName, token) {
+	return `https://x-access-token:${token}@github.com/${repoFullName}.git`;
+}
+function cleanUrl(repoFullName) {
+	return `https://github.com/${repoFullName}.git`;
+}
+/**
+* Materialize the repo inside the user's sandbox. Clones on first open, pulls on
+* re-open. Always scrubs the install token from the remote afterwards and sets
+* `materialized_at` on the per-user sandbox binding row.
+*
+*/
+async function materializeRepo(options) {
+	const { row: sandboxRow, repoInfo, sandbox, token, storage, onProgress } = 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 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 authUrl = tokenUrl(repo, token);
+	const alreadyMaterialized = await hasExistingCheckout(sandbox, workdir, repo);
+	let succeeded = false;
+	try {
+		if (!alreadyMaterialized) {
+			reportProgress(onProgress, {
+				phase: "cloning",
+				message: `Cloning ${repo} (first open can take a minute)…`
+			});
+			const clone = await sh(sandbox, `git clone --depth=1 --single-branch --branch ${shellQuote(repoInfo.defaultBranch)} ${shellQuote(authUrl)} ${shellQuote(workdir)}`, { phase: "repository clone" });
+			if (clone.exitCode !== 0) throw classifyGitFailure(clone, "clone-failed");
+		} else {
+			reportProgress(onProgress, {
+				phase: "pulling",
+				message: `Updating ${repo} to the latest changes…`
+			});
+			const setUrl = await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(authUrl)}`);
+			if (setUrl.exitCode !== 0) throw new MaterializeError(`Failed to set git remote: ${setUrl.stderr}`, "pull-failed");
+			const pull = await sh(sandbox, `git -C ${shellQuote(workdir)} pull --ff-only`, { phase: "repository pull" });
+			if (pull.exitCode !== 0) {
+				if (!isBenignNonFastForward(pull)) throw classifyGitFailure(pull, "pull-failed");
+				reportProgress(onProgress, {
+					phase: "pulling",
+					message: "Workspace has local changes that diverge from the remote — keeping them as-is."
+				});
+			}
+		}
+		succeeded = true;
+	} finally {
+		await scrubRemote(sandbox, workdir, repo, succeeded);
+	}
+	reportProgress(onProgress, {
+		phase: "finalizing",
+		message: "Finalizing workspace…"
+	});
+	await storage.markMaterialized({ id: sandboxRow.id });
+}
+/**
+* Reset a pooled workdir that a new session just claimed: the previous
+* session's branch and dirty state must not leak into the new session, so
+* force-checkout the default branch and drop all local modifications. When
+* the claimed VM was reaped and re-provisioned there is no checkout yet and
+* this is a no-op (the clone path handles it). A wedged checkout falls back
+* to wiping the workdir so `materializeRepo` re-clones inside the same VM
+* instead of permanently failing the session.
+*/
+async function recycleClaimedWorkdir(sandbox, workdir, defaultBranch) {
+	if (!/^[A-Za-z0-9_./-]+$/.test(defaultBranch)) throw new MaterializeError(`Refusing to recycle: invalid default branch '${defaultBranch}'.`, "clone-failed");
+	const w = shellQuote(workdir);
+	if ((await sh(sandbox, `git -C ${w} rev-parse --is-inside-work-tree`)).exitCode !== 0) return;
+	const recycle = await sh(sandbox, `git -C ${w} checkout -f ${shellQuote(defaultBranch)} && git -C ${w} reset --hard && git -C ${w} clean -fdx`, { phase: "claimed workdir recycle" });
+	if (recycle.exitCode === 0) return;
+	if ((await sh(sandbox, `rm -rf ${w}`)).exitCode !== 0) throw new MaterializeError(`Failed to recycle claimed sandbox workdir: ${recycle.stderr}`, "clone-failed");
+}
+/** Check out a session's branch inside its isolated repository clone. */
+async function checkoutSessionBranch(sandbox, workdir, { branch, baseBranch, token, repoFullName }) {
+	if (!isValidGitRef(branch) || !isValidGitRef(baseBranch)) throw new MaterializeError("Refusing to create a session from an invalid branch name.", "clone-failed");
+	const current = await sh(sandbox, `git -C ${shellQuote(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 (checkout.exitCode !== 0) {
+			if (isBlockedByLocalWork(checkout)) return;
+			throw classifyGitFailure(checkout, "clone-failed");
+		}
+		return;
+	}
+	const authUrl = tokenUrl(repoFullName, token);
+	try {
+		const setUrl = await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(authUrl)}`);
+		if (setUrl.exitCode !== 0) throw classifyGitFailure(setUrl, "pull-failed");
+		const fetch = await sh(sandbox, `git -C ${shellQuote(workdir)} fetch origin ${shellQuote(baseBranch)} && 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;
+			throw classifyGitFailure(fetch, "clone-failed");
+		}
+	} finally {
+		await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(cleanUrl(repoFullName))}`);
+	}
+}
+/**
+* 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);
+}
+/**
+* True when the workdir already holds a git checkout whose `origin` points at
+* this exact repo. Matches both the clean and token-auth URL forms; any other
+* remote (or no git dir at all) falls back to the clone path.
+*/
+async function hasExistingCheckout(sandbox, workdir, repoFullName) {
+	const result = await sh(sandbox, `git -C ${shellQuote(workdir)} remote get-url origin`);
+	if (result.exitCode !== 0) return false;
+	const url = result.stdout.trim().toLowerCase();
+	const suffix = `github.com/${repoFullName.toLowerCase()}`;
+	return url.endsWith(`${suffix}.git`) || url.endsWith(suffix);
+}
+/**
+* Reset the git remote back to the tokenless URL. On a successful clone/pull the
+* workdir always has a `.git`, so a non-zero exit code here means the token may
+* still be persisted — surface it. On the failure path the workdir may not exist
+* (e.g. a failed clone), so a non-zero exit is tolerated — and never masks the
+* primary failure being thrown through the `finally`.
+*/
+async function scrubRemote(sandbox, workdir, repoFullName, expectGitDir) {
+	const result = await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(cleanUrl(repoFullName))}`);
+	if (result.exitCode !== 0 && expectGitDir) throw new MaterializeError(`Failed to scrub installation token from git remote: ${result.stderr.trim() || result.stdout.trim()}`, "pull-failed");
+}
+/**
+* True when a failed `git pull --ff-only` on re-open just means the current
+* branch can't be fast-forwarded — not that anything is broken. The shared
+* workdir is routinely left on a session's working branch, which may have
+* local commits diverging from upstream, no upstream at all (session branches
+* are created from `FETCH_HEAD`), or a detached HEAD. A checkout can also
+* hold uncommitted or untracked files (a build or script run left residue,
+* or an older session worked directly in the shared checkout), which makes
+* git refuse the merge outright. In all of these cases the checkout is
+* intact and may hold real work; materialization must keep it as-is rather
+* than fail the workspace open — and must never discard the local state to
+* force the pull through.
+*/
+function isBenignNonFastForward(result) {
+	const output = `${result.stderr || ""}\n${result.stdout || ""}`;
+	return /Not possible to fast-forward|Diverging branches can't be fast-forwarded|no tracking information for the current branch|You are not currently on a branch|Your local changes to the following files would be overwritten by merge|untracked working tree files would be overwritten by merge/i.test(output);
+}
+/**
+* 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);
+}
+/**
+* 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.
+*/
+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 `user.name` / `user.email` for the given repo working tree inside
+* the sandbox so commits are authored correctly. Values are shell-quoted.
+*/
+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)}`);
+	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)}`);
+	if (setEmail.exitCode !== 0) throw new MaterializeError(`Failed to set git user.email: ${setEmail.stderr.trim()}`, "commit-failed");
+}
+/**
+* Temporarily rewrite `origin` to a tokenized URL, run `fn` (e.g. a push), and
+* **always** scrub the remote back to the tokenless URL in a `finally`. 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.
+*
+* On the success path the scrub must succeed (a leaked token is a hard error);
+* if it fails we surface it. On the failure path the scrub is best-effort but
+* still attempted, and the original operation error is rethrown.
+*/
+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");
+	}
+	try {
+		return await fn();
+	} finally {
+		await scrubRemote(sandbox, workdir, repoFullName, true);
+	}
+}
+/**
+* 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.
+*/
+async function pushBranch(sandbox, workdir, branch, token, 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");
+	});
+}
+/**
+* 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 worktree (or repo) path to commit in
+* @param message  the commit message (quoted; arbitrary text is safe)
+* @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`);
+	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 (commit.exitCode !== 0) throw new MaterializeError(`git commit failed: ${commit.stderr.trim() || commit.stdout.trim()}`, "commit-failed");
+	return { committed: true };
+}
+/** Error raised when a worktree cannot be created/reused inside the sandbox. */
+var WorktreeError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "WorktreeError";
+	}
+};
+/**
+* Reduce a (already ref-validated) branch name to a filesystem-safe directory
+* segment for the worktree path: slashes/dots/unsafe chars collapsed to `-`.
+* This only affects the *directory name*, never the git branch itself.
+*
+* Sanitization is lossy (e.g. `feat/a` and `feat-a` both reduce to `feat-a`),
+* so an 8-char hash of the original branch is appended whenever the sanitized
+* form differs from the input. That keeps clean names (`main`) readable while
+* guaranteeing distinct branches never share a worktree directory.
+*/
+function safeBranchDir(branch) {
+	const sanitized = branch.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/\/+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, 100) || "work";
+	if (sanitized === branch) return sanitized;
+	return `${sanitized}-${createHash("sha256").update(branch).digest("hex").slice(0, 8)}`;
+}
+/**
+* Compute the absolute worktree path for a branch, server-side only. Worktrees
+* live alongside the repo checkout under a sibling `worktrees/` directory so the
+* repo's `.git` is shared. Never derived from client-supplied paths.
+*/
+function computeWorktreePath(repoWorkdir, branch) {
+	return `${repoWorkdir.replace(/\/+$/, "").split("/").slice(0, -1).join("/") || ""}/worktrees/${safeBranchDir(branch)}`;
+}
+/**
+* Create (or reuse) a git worktree + branch inside the sandbox for a unit of
+* work. Idempotent: if a worktree already exists at the computed path it is
+* reused. The branch is created from the freshly fetched `origin/<baseBranch>`
+* — never the sandbox's possibly stale local ref — so new worktrees always
+* start from the latest remote state.
+*
+* @param sandbox       live sandbox containing the base checkout
+* @param repoWorkdir   the base repo checkout path inside the sandbox
+* @param branch        the feature branch (ref-validated server-side)
+* @param baseBranch    the branch to fork from (ref-validated; defaults to the repo's default branch)
+* @param token         short-lived installation token used only for the base-branch fetch
+* @param repoFullName  `owner/repo` used to build the tokenized remote URL
+*/
+async function ensureWorktree(sandbox, repoWorkdir, { branch, baseBranch, token, repoFullName }) {
+	if (!isValidGitRef(branch)) throw new WorktreeError(`Invalid branch name '${branch}'.`, "invalid-branch");
+	if (!isValidGitRef(baseBranch)) throw new WorktreeError(`Invalid base branch name '${baseBranch}'.`, "invalid-branch");
+	const worktreePath = computeWorktreePath(repoWorkdir, branch);
+	if ((await sh(sandbox, `test -e ${shellQuote(`${worktreePath}/.git`)}`)).exitCode === 0) return {
+		worktreePath,
+		branch,
+		baseBranch,
+		reused: true
+	};
+	const baseRef = `origin/${baseBranch}`;
+	await withInstallToken(sandbox, repoWorkdir, repoFullName, token, async () => {
+		const fetch = await sh(sandbox, `git -C ${shellQuote(repoWorkdir)} fetch origin ${shellQuote(`+refs/heads/${baseBranch}:refs/remotes/${baseRef}`)}`);
+		if (fetch.exitCode !== 0) throw classifyGitFailure(fetch, "pull-failed");
+	});
+	const add = await sh(sandbox, `git -C ${shellQuote(repoWorkdir)} worktree add --no-track -B ${shellQuote(branch)} ${shellQuote(worktreePath)} ${shellQuote(baseRef)}`);
+	if (add.exitCode !== 0) throw new WorktreeError(`git worktree add failed: ${add.stderr.trim() || add.stdout.trim()}`, "worktree-failed");
+	return {
+		worktreePath,
+		branch,
+		baseBranch,
+		reused: false
+	};
+}
+/**
+* Run the project's setup command (e.g. `pnpm i && pnpm build`) inside a
+* freshly created worktree. Called before the worktree is handed to any agent
+* run so the checkout 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 worktree
+* @param worktreePath  the server-computed worktree path the command runs in
+* @param command       the org-configured setup shell command
+*/
+async function runWorktreeSetup(sandbox, worktreePath, command) {
+	const result = await sh(sandbox, `cd ${shellQuote(worktreePath)} && { ${command}\n}`, { phase: "worktree setup" });
+	if (result.exitCode !== 0) {
+		const detail = (result.stderr.trim() || result.stdout.trim()).slice(-2e3);
+		throw new WorktreeError(`Setup command failed (exit ${result.exitCode}): ${detail}`, "setup-failed");
+	}
+}
+/**
+* Remove a worktree (and its local feature branch) from the sandbox. The
+* checkout is removed with `--force` — the caller owns confirming that any
+* uncommitted work in it can be discarded. Idempotent: a worktree whose
+* directory is already gone only has its metadata pruned.
+*
+* @param sandbox       live sandbox containing the base checkout
+* @param repoWorkdir   the base repo checkout path inside the sandbox
+* @param branch        the worktree's feature branch (ref-validated)
+* @param worktreePath  the persisted, server-computed worktree path
+*/
+async function removeWorktree(sandbox, repoWorkdir, { branch, worktreePath }) {
+	if (!isValidGitRef(branch)) throw new WorktreeError(`Invalid branch name '${branch}'.`, "invalid-branch");
+	const remove = await sh(sandbox, `git -C ${shellQuote(repoWorkdir)} worktree remove --force ${shellQuote(worktreePath)}`);
+	if (remove.exitCode !== 0) {
+		await sh(sandbox, `git -C ${shellQuote(repoWorkdir)} worktree prune`);
+		if ((await sh(sandbox, `test -e ${shellQuote(worktreePath)}`)).exitCode === 0) throw new WorktreeError(`git worktree remove failed: ${remove.stderr.trim() || remove.stdout.trim()}`, "worktree-failed");
+	}
+	await sh(sandbox, `git -C ${shellQuote(repoWorkdir)} branch -D ${shellQuote(branch)}`);
+}
+/**
+* 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 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");
+}
+/** 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 shell-quoted, 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 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}`);
+	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, MaterializeError, WorktreeError, checkoutSessionBranch, commitAll, computeWorktreePath, configureGitIdentity, createPullRequest, ensureProjectSandbox, ensureWorktree, isValidGitRef, materializeRepo, pushBranch, recycleClaimedWorkdir, removeWorktree, resolveGitIdentity, runWorktreeSetup, safeBranchDir, shellQuote, teardownProjectSandbox, withInstallToken };
+
+//# sourceMappingURL=sandbox.js.map