@mastra/factory 0.2.2-alpha.1 → 0.2.2-alpha.2

package/dist/integrations/github/sandbox.js

@@ -1,401 +1,456 @@
-// src/integrations/github/sandbox.ts
+import { reportProgress } from "../../sandbox/fleet.js";
 import { createHash } from "crypto";
-
-// src/sandbox/fleet.ts
-import path from "path";
-function reportProgress(onProgress, event) {
-  if (!onProgress) return;
-  try {
-    onProgress(event);
-  } catch {
-  }
-}
-
-// src/integrations/github/sandbox.ts
+//#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 })
-  };
+	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);
+	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);
+	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(`'\\''`) + `'`;
+	return `'` + value.split(`'`).join(`'\\''`) + `'`;
 }
-var DEFAULT_COMMAND_TIMEOUT_MS = 15 * 6e4;
-var CHECKOUT_COMMAND_TIMEOUT_MS = 5 * 6e4;
+/**
+* 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;
+/** Run a shell script in the sandbox via `sh -c`, bounded by a hang guard. */
 async function sh(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(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);
-  }
+	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 {
-  constructor(message, code) {
-    super(message);
-    this.code = code;
-    this.name = "MaterializeError";
-  }
-  code;
+	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`;
+	return `https://x-access-token:${token}@github.com/${repoFullName}.git`;
 }
 function cleanUrl(repoFullName) {
-  return `https://github.com/${repoFullName}.git`;
+	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"
-    );
-  }
-  const gitVersion = await sh(sandbox, "git --version");
-  if (gitVersion.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)\u2026`
-      });
-      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\u2026` });
-      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) {
-        throw classifyGitFailure(pull, "pull-failed");
-      }
-    }
-    succeeded = true;
-  } finally {
-    await scrubRemote(sandbox, workdir, repo, succeeded);
-  }
-  reportProgress(onProgress, { phase: "finalizing", message: "Finalizing workspace\u2026" });
-  await storage.markMaterialized({ id: sandboxRow.id });
+	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) throw classifyGitFailure(pull, "pull-failed");
+		}
+		succeeded = true;
+	} finally {
+		await scrubRemote(sandbox, workdir, repo, succeeded);
+	}
+	reportProgress(onProgress, {
+		phase: "finalizing",
+		message: "Finalizing workspace…"
+	});
+	await storage.markMaterialized({ id: sandboxRow.id });
 }
-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;
-  const local = await sh(
-    sandbox,
-    `git -C ${shellQuote(workdir)} show-ref --verify --quiet refs/heads/${shellQuote(branch)}`
-  );
-  if (local.exitCode === 0) {
-    const checkout = await sh(sandbox, `git -C ${shellQuote(workdir)} checkout ${shellQuote(branch)}`);
-    if (checkout.exitCode !== 0) 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) throw classifyGitFailure(fetch, "clone-failed");
-  } finally {
-    await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(cleanUrl(repoFullName))}`);
-  }
+/** 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) 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) throw classifyGitFailure(fetch, "clone-failed");
+	} finally {
+		await sh(sandbox, `git -C ${shellQuote(workdir)} remote set-url origin ${shellQuote(cleanUrl(repoFullName))}`);
+	}
 }
+/**
+* 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);
+	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"
-    );
-  }
+	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");
 }
+/**
+* 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"
-    );
-  }
-  const verb = fallback === "clone-failed" ? "clone" : fallback === "pull-failed" ? "pull" : "push";
-  return new MaterializeError(`git ${verb} failed: ${stderr}`, 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 && // Reject leading-dash refs (e.g. `--mirror`) so the value can never be
-  // parsed as a git option when interpolated into a command.
-  !value.startsWith("-") && /^[A-Za-z0-9_./-]+$/.test(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();
-  const name = (identity.name || "").trim() || login || "Mastra Code";
-  const email = (identity.email || "").trim() || (login ? `${login}@users.noreply.github.com` : "mastra-code@users.noreply.github.com");
-  return { name, email };
+	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");
-  }
+	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);
-  }
+	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");
-    }
-  });
+	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");
-  }
-  const staged = await sh(sandbox, `git -C ${shellQuote(workdir)} diff --cached --quiet`);
-  if (staged.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 };
+	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 {
-  constructor(message, code) {
-    super(message);
-    this.code = code;
-    this.name = "WorktreeError";
-  }
-  code;
+	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;
-  const hash = createHash("sha256").update(branch).digest("hex").slice(0, 8);
-  return `${sanitized}-${hash}`;
+	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) {
-  const parent = repoWorkdir.replace(/\/+$/, "").split("/").slice(0, -1).join("/") || "";
-  return `${parent}/worktrees/${safeBranchDir(branch)}`;
+	return `${repoWorkdir.replace(/\/+$/, "").split("/").slice(0, -1).join("/") || ""}/worktrees/${safeBranchDir(branch)}`;
 }
-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);
-  const exists = await sh(sandbox, `test -e ${shellQuote(`${worktreePath}/.git`)}`);
-  if (exists.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 };
+/**
+* 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}
-}`, { 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");
-  }
+	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`);
-    const exists = await sh(sandbox, `test -e ${shellQuote(worktreePath)}`);
-    if (exists.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)}`);
+	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) {
-  const version = await sh(sandbox, "gh --version");
-  if (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 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) {
-  const match = stdout.match(/https:\/\/github\.com\/[^\s]+\/pull\/\d+/);
-  return match?.[0];
+	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 script = `cd ${shellQuote(workdir)} && ${ghCommand}`;
-  const result = await sh(sandbox, script);
-  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 };
+	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 };
 }
-export {
-  CHECKOUT_COMMAND_TIMEOUT_MS,
-  MaterializeError,
-  WorktreeError,
-  checkoutSessionBranch,
-  commitAll,
-  computeWorktreePath,
-  configureGitIdentity,
-  createPullRequest,
-  ensureProjectSandbox,
-  ensureWorktree,
-  isValidGitRef,
-  materializeRepo,
-  pushBranch,
-  removeWorktree,
-  resolveGitIdentity,
-  runWorktreeSetup,
-  safeBranchDir,
-  shellQuote,
-  teardownProjectSandbox,
-  withInstallToken
-};
+//#endregion
+export { CHECKOUT_COMMAND_TIMEOUT_MS, MaterializeError, WorktreeError, checkoutSessionBranch, commitAll, computeWorktreePath, configureGitIdentity, createPullRequest, ensureProjectSandbox, ensureWorktree, isValidGitRef, materializeRepo, pushBranch, removeWorktree, resolveGitIdentity, runWorktreeSetup, safeBranchDir, shellQuote, teardownProjectSandbox, withInstallToken };
+
 //# sourceMappingURL=sandbox.js.map