@themoltnet/sandbox-gondolin 0.1.0

package/dist/index.js

@@ -0,0 +1,867 @@
+import path, { isAbsolute, relative } from "node:path";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { MemoryProvider, RealFSProvider, ShadowProvider, VM, VmCheckpoint, createHttpHooks, createShadowPathPredicate, ensureImageSelector, isWriteFlag, loadGuestAssets } from "@earendil-works/gondolin";
+import { parseEnv } from "node:util";
+//#region src/abort-utils.ts
+function throwIfAborted(signal, label) {
+	if (!signal?.aborted) return;
+	throw abortError(label, signal);
+}
+function abortError(label, signal) {
+	const reason = signal.reason;
+	const suffix = reason instanceof Error ? reason.message : reason === void 0 ? "aborted" : String(reason);
+	const err = /* @__PURE__ */ new Error(`${label} aborted: ${suffix}`);
+	err.name = "AbortError";
+	return err;
+}
+function cleanupLateResource(resourcePromise, opts) {
+	resourcePromise.then(async (resource) => {
+		try {
+			await opts.cleanup(resource);
+		} catch (err) {
+			opts.onCleanupError?.(err);
+		}
+	}, () => {});
+}
+async function abortableResource(opts) {
+	const { signal } = opts;
+	if (!signal) return opts.promise;
+	throwIfAborted(signal, opts.label);
+	const resourcePromise = Promise.resolve(opts.promise);
+	const abortPromise = new Promise((_, reject) => {
+		const abort = () => {
+			cleanupLateResource(resourcePromise, opts);
+			reject(abortError(opts.label, signal));
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		resourcePromise.then(() => signal.removeEventListener("abort", abort), () => signal.removeEventListener("abort", abort));
+	});
+	return Promise.race([resourcePromise, abortPromise]);
+}
+async function delay(ms, signal, label) {
+	if (!signal) {
+		await new Promise((resolve) => {
+			setTimeout(resolve, ms);
+		});
+		return;
+	}
+	throwIfAborted(signal, label);
+	await new Promise((resolve, reject) => {
+		const listener = () => {
+			clearTimeout(timeout);
+			reject(abortError(label, signal));
+		};
+		const timeout = setTimeout(() => {
+			signal.removeEventListener("abort", listener);
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", listener, { once: true });
+	});
+}
+//#endregion
+//#region src/path-containment.ts
+/**
+* Check containment for already-resolved lexical or real paths.
+*
+* Callers that accept untrusted paths must resolve/realpath at their I/O
+* boundary first; keeping the platform-specific relative-path rule here avoids
+* subtly different `..` and absolute-path handling across runtime cleanup,
+* session sync, and artifact staging.
+*/
+function isResolvedPathInsideRoot(path, root) {
+	const rel = relative(root, path);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+//#endregion
+//#region src/snapshot.ts
+/**
+* Snapshot builder with auto-build and caching.
+*
+* Builds a Gondolin VM snapshot in two layers:
+*   1. Base (always): Alpine essentials, git, gh CLI, MoltNet CLI, agent user
+*   2. User setup commands (optional): arbitrary shell commands on top of the base
+*
+* Consumers provide raw shell commands — no abstraction over package managers
+* or runtimes. The base provides curl, git, tar, jq; everything else is up to
+* the setup commands.
+*
+* Caches in a platform-appropriate directory:
+*   - macOS: ~/Library/Caches/moltnet/gondolin/
+*   - Linux: ~/.cache/moltnet/gondolin/
+*
+* The cache key is a hash of the full config. When any input changes,
+* a new snapshot is built automatically.
+*/
+/** Alpine packages whose commands are guaranteed in every snapshot. */
+var BASE_ALPINE_PACKAGE_EXECUTABLES = {
+	curl: "curl",
+	file: "file",
+	git: "git",
+	jq: "jq",
+	ripgrep: "rg",
+	tar: "tar",
+	xz: "xz"
+};
+/** Alpine packages required by every snapshot. */
+var BASE_ALPINE_PACKAGES = ["ca-certificates", ...Object.keys(BASE_ALPINE_PACKAGE_EXECUTABLES)];
+/** Commands guaranteed by the base Gondolin snapshot. */
+var GONDOLIN_BASE_EXECUTABLES = Object.freeze([
+	...Object.values(BASE_ALPINE_PACKAGE_EXECUTABLES),
+	"gh",
+	"moltnet"
+].sort());
+/** gh CLI version installed in every snapshot. */
+var GH_VERSION = "2.74.0";
+/** MoltNet CLI version — downloaded as a binary, no Node needed. */
+var MOLTNET_CLI_VERSION = "1.37.0";
+/**
+* Resolve guest architecture from host (Gondolin VMs match host arch).
+*
+* The two naming conventions are NOT interchangeable:
+*   - `gh`  — GitHub release-asset suffix (gh CLI ships `linux_amd64.tar.gz`,
+*             `linux_arm64.tar.gz`).
+*   - `npm` — npm optionalDependencies naming, which mirrors Node's
+*             `process.arch` values (`x64`, `arm64`). The MoltNet CLI is
+*             published as `@themoltnet/cli-linux-x64` and
+*             `@themoltnet/cli-linux-arm64`, NOT `cli-linux-amd64`.
+*/
+function getGuestArch() {
+	if (process.arch === "arm64") return {
+		gh: "linux_arm64",
+		npm: "linux-arm64"
+	};
+	return {
+		gh: "linux_amd64",
+		npm: "linux-x64"
+	};
+}
+/** Hosts reachable during snapshot build. */
+var SETUP_ALLOWED_HOSTS = [
+	"dl-cdn.alpinelinux.org",
+	"*.alpinelinux.org",
+	"registry.npmjs.org",
+	"*.npmjs.org",
+	"nodejs.org",
+	"*.nodejs.org",
+	"unofficial-builds.nodejs.org",
+	"github.com",
+	"*.github.com",
+	"*.githubusercontent.com",
+	"objects.githubusercontent.com"
+];
+var DEFAULT_CONFIG = {};
+function getCacheDir() {
+	if (process.platform === "darwin") return path.join(process.env.HOME ?? "/tmp", "Library", "Caches", "moltnet", "gondolin");
+	const base = process.env.XDG_CACHE_HOME ?? path.join(process.env.HOME ?? "/tmp", ".cache");
+	return path.join(base, "moltnet", "gondolin");
+}
+function computeConfigHash(config) {
+	const h = createHash("sha256");
+	h.update(JSON.stringify({
+		baseAlpine: BASE_ALPINE_PACKAGES,
+		ghVersion: GH_VERSION,
+		cliVersion: MOLTNET_CLI_VERSION,
+		config
+	}));
+	return h.digest("hex").slice(0, 12);
+}
+function getSnapshotPath(config) {
+	const hash = computeConfigHash(config);
+	const dir = path.join(getCacheDir(), `v2-${hash}`);
+	return path.join(dir, "snapshot.qcow2");
+}
+/**
+* Ensure a cached snapshot exists, building one if needed.
+* Returns the absolute path to the qcow2 checkpoint file.
+*/
+async function ensureSnapshot(options = {}) {
+	const config = options.config ?? DEFAULT_CONFIG;
+	const log = options.onProgress ?? (() => {});
+	const maxCached = options.maxCached ?? 1;
+	const snapshotPath = getSnapshotPath(config);
+	const snapshotDir = path.dirname(snapshotPath);
+	if (existsSync(snapshotPath)) {
+		log(`snapshot cache hit: ${snapshotPath}`);
+		return snapshotPath;
+	}
+	log("snapshot cache miss — building (this takes 1-3 minutes)...");
+	mkdirSync(snapshotDir, { recursive: true });
+	const overlayPath = path.join(snapshotDir, "build.overlay.qcow2");
+	if (existsSync(overlayPath)) rmSync(overlayPath);
+	if (existsSync(snapshotPath)) rmSync(snapshotPath);
+	log("resolving alpine-base image...");
+	const assets = loadGuestAssets((await ensureImageSelector("alpine-base")).assetDir);
+	const overlaySize = config.overlaySize ?? "3G";
+	log(`creating qcow2 overlay (${overlaySize})...`);
+	execFileSync("qemu-img", [
+		"create",
+		"-f",
+		"qcow2",
+		"-F",
+		"raw",
+		"-b",
+		assets.rootfsPath,
+		overlayPath,
+		overlaySize
+	], { stdio: "pipe" });
+	const { httpHooks } = createHttpHooks({ allowedHosts: [...SETUP_ALLOWED_HOSTS, ...config.allowedHosts ?? []] });
+	log("booting VM for setup...");
+	const vm = await VM.create({
+		httpHooks,
+		env: {
+			PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/lib/go/bin",
+			HOME: "/root",
+			GOROOT: "/usr/lib/go",
+			GOPATH: "/root/go"
+		},
+		sandbox: {
+			rootDiskPath: overlayPath,
+			rootDiskFormat: "qcow2",
+			rootDiskReadOnly: false,
+			rootDiskDeleteOnClose: false
+		}
+	});
+	try {
+		await buildSnapshot(vm, config, log);
+		log("creating checkpoint...");
+		await vm.checkpoint(snapshotPath);
+		log(`snapshot saved: ${snapshotPath}`);
+	} finally {
+		try {
+			await vm.close();
+		} catch {}
+		if (existsSync(overlayPath)) rmSync(overlayPath, { force: true });
+	}
+	pruneOldSnapshots(maxCached, snapshotDir);
+	return snapshotPath;
+}
+/** Helper: run a command in the VM, throw on failure. */
+async function run(vm, log, label, cmd) {
+	log(label);
+	const r = await vm.exec(cmd);
+	if (r.exitCode !== 0) {
+		const output = [r.stderr, r.stdout].filter(Boolean).join("\n").slice(0, 800);
+		throw new Error(`snapshot build "${label}" failed (exit ${r.exitCode}):\n${output}`);
+	}
+}
+async function buildSnapshot(vm, config, log) {
+	await run(vm, log, "resizing rootfs...", "apk add --no-cache e2fsprogs-extra >/dev/null 2>&1 && resize2fs /dev/vda 2>/dev/null");
+	await run(vm, log, `installing base packages: ${BASE_ALPINE_PACKAGES.join(" ")}`, `apk add --no-cache ${BASE_ALPINE_PACKAGES.join(" ")}`);
+	const arch = getGuestArch();
+	await run(vm, log, `installing gh ${GH_VERSION} (${arch.gh})...`, `sh -eu -c '
+      curl -fsSL "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_${arch.gh}.tar.gz" -o /tmp/gh.tar.gz
+      tar -xzf /tmp/gh.tar.gz -C /tmp
+      mv /tmp/gh_${GH_VERSION}_${arch.gh}/bin/gh /usr/local/bin/gh
+      chmod +x /usr/local/bin/gh
+      rm -rf /tmp/gh.tar.gz /tmp/gh_${GH_VERSION}_${arch.gh}
+      gh --version
+    '`);
+	await run(vm, log, `installing moltnet CLI ${MOLTNET_CLI_VERSION} (${arch.npm})...`, `sh -eu -c '
+      curl -fsSL "https://registry.npmjs.org/@themoltnet/cli-${arch.npm}/-/cli-${arch.npm}-${MOLTNET_CLI_VERSION}.tgz" -o /tmp/moltnet.tgz
+      tar -xzf /tmp/moltnet.tgz -C /tmp
+      mv /tmp/package/bin/moltnet /usr/local/bin/moltnet
+      chmod +x /usr/local/bin/moltnet
+      rm -rf /tmp/moltnet.tgz /tmp/package
+    '`);
+	await run(vm, log, "creating agent user...", `sh -eu -c '
+      addgroup -g 501 agent 2>/dev/null || true
+      adduser -D -u 501 -G agent -h /home/agent -s /bin/sh agent 2>/dev/null || true
+      mkdir -p /home/agent/.moltnet /home/agent/.cache
+      chown -R agent:agent /home/agent
+      chmod 644 /etc/gondolin/mitm/ca.crt 2>/dev/null || true
+    '`);
+	await run(vm, log, "configuring DNS resolvers...", `sh -c 'echo "nameserver 8.8.8.8
+nameserver 1.1.1.1" > /etc/resolv.conf'`);
+	if (config.setupCommands?.length) for (let i = 0; i < config.setupCommands.length; i++) await run(vm, log, `setup [${i + 1}/${config.setupCommands.length}]...`, config.setupCommands[i]);
+}
+function pruneOldSnapshots(maxCached, currentDir) {
+	const cacheRoot = getCacheDir();
+	if (!existsSync(cacheRoot)) return;
+	const entries = readdirSync(cacheRoot, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name.startsWith("v")).map((e) => {
+		const fullPath = path.join(cacheRoot, e.name);
+		return {
+			path: fullPath,
+			mtime: statSync(fullPath).mtimeMs
+		};
+	}).sort((a, b) => b.mtime - a.mtime);
+	for (const entry of entries.slice(maxCached + 1)) if (entry.path !== currentDir) rmSync(entry.path, {
+		recursive: true,
+		force: true
+	});
+}
+//#endregion
+//#region src/vm-manager.ts
+/**
+* Memory-backed VFS mount used by the daemon to inject task context
+* (#943 slice 1.5). This is a separate top-level mount because Gondolin
+* mounts can't nest. The agent's Gondolin-bound Read tool accepts paths
+* under this prefix (see toGuestPath in tool-operations.ts).
+*
+* Why MemoryProvider rather than a path under the workspace mount:
+*   - Injected task context is ephemeral by intent: per-task-attempt input
+*     scoped to the VM lifetime. MemoryProvider models that exactly —
+*     in-memory, per-VM-instance, zero host artefacts, automatic
+*     cleanup on VM close.
+*   - Writing under the workspace mount fails in worktrees because we symlink
+*     `.moltnet/` to the main repo (so credentials are reachable from
+*     worktrees), and Gondolin's RealFSProvider correctly refuses to
+*     create paths whose ancestors' realpath escapes the mount root.
+*     That refusal is a deliberate sandbox-escape protection, not a
+*     bug. See diary semantic entry cd27d9d3-efdc-4aec-ac0d-5fd8ce258d1f
+*     and episodic 7affbfeb-18a2-4963-aeac-c177eb2afa2d for the full
+*     investigation and the alternatives we rejected.
+*/
+var GUEST_TASK_CONTEXT_MOUNT = "/moltnet-task-context";
+/** @deprecated Use GUEST_TASK_CONTEXT_MOUNT. */
+var GUEST_TASK_SKILLS_MOUNT = GUEST_TASK_CONTEXT_MOUNT;
+function resolveVfsShadowConfig(config) {
+	const patterns = config?.vfs?.shadow ?? [];
+	if (patterns.length === 0) return {
+		mode: "none",
+		patterns: []
+	};
+	return {
+		mode: config?.vfs?.shadowMode ?? "tmpfs",
+		patterns
+	};
+}
+function shouldRunResumeCommand(entry, ctx) {
+	if (typeof entry === "string") return true;
+	const workspaceModes = entry.when?.workspaceMode;
+	if (workspaceModes && !workspaceModes.includes(ctx.workspaceMode)) return false;
+	return true;
+}
+function shouldShadowNodeModulesPath(pathname) {
+	const normalized = path.posix.normalize(pathname);
+	return normalized === "/node_modules" || normalized.startsWith("/node_modules/") || normalized.endsWith("/node_modules") || normalized.includes("/node_modules/");
+}
+function isNodeModulesBinPath(pathname) {
+	const normalized = path.posix.normalize(pathname);
+	return normalized.includes("/node_modules/.bin/") || normalized.startsWith("/node_modules/.bin/");
+}
+var AutoParentMemoryProvider = class extends MemoryProvider {
+	ensureParentDir(pathname) {
+		const parent = path.posix.dirname(path.posix.normalize(pathname));
+		if (!parent || parent === "/" || parent === ".") return;
+		this.mkdirSync(parent, { recursive: true });
+	}
+	async mkdir(pathname, options) {
+		this.ensureParentDir(pathname);
+		return super.mkdir(pathname, options);
+	}
+	mkdirSync(pathname, options) {
+		this.ensureParentDir(pathname);
+		return super.mkdirSync(pathname, options);
+	}
+	async open(pathname, flags, mode) {
+		if (isWriteFlag(flags)) this.ensureParentDir(pathname);
+		return super.open(pathname, flags, isWriteFlag(flags) && isNodeModulesBinPath(pathname) ? (mode ?? 493) | 73 : mode);
+	}
+	openSync(pathname, flags, mode) {
+		if (isWriteFlag(flags)) this.ensureParentDir(pathname);
+		return super.openSync(pathname, flags, isWriteFlag(flags) && isNodeModulesBinPath(pathname) ? (mode ?? 493) | 73 : mode);
+	}
+};
+/**
+* Resolve the main worktree root (where .moltnet/ lives — it's untracked,
+* only exists in the main worktree, not in git worktrees).
+*/
+function findMainWorktree(startPath = process.cwd()) {
+	let output;
+	try {
+		output = execFileSync("git", [
+			"-C",
+			startPath,
+			"worktree",
+			"list",
+			"--porcelain"
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		});
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Git worktree discovery requires a git repository: ${message}`);
+	}
+	for (const block of output.split("\n\n")) {
+		const lines = block.split("\n");
+		const wt = lines.find((l) => l.startsWith("worktree "));
+		if (wt && !lines.some((l) => l === "bare")) return wt.replace("worktree ", "");
+	}
+	throw new Error("Could not find main git worktree");
+}
+function resolveVmAgentDir(config) {
+	const rootDir = config.agentRootDir ?? findMainWorktree();
+	return path.join(rootDir, ".moltnet", config.agentName);
+}
+function loadCredentials(agentDir, mode = "guest-config", onDiagnostic, providerAuth) {
+	const moltnetPath = path.join(agentDir, "moltnet.json");
+	const agentEnvPath = path.join(agentDir, "env");
+	const providerAuthJson = providerAuth?.load() ?? null;
+	if (mode === "host-authenticated") return {
+		moltnetJson: "",
+		agentEnvRaw: "",
+		providerAuthJson,
+		agentEnv: {},
+		gitconfig: null,
+		sshPrivateKey: null,
+		sshPublicKey: null,
+		allowedSigners: null,
+		githubAppPem: null,
+		githubAppPemFilename: null
+	};
+	const hasMoltnetJson = existsSync(moltnetPath);
+	const hasAgentEnv = existsSync(agentEnvPath);
+	if (!hasMoltnetJson || !hasAgentEnv) throw new Error(`Guest credential mode requires both ${moltnetPath} and ${agentEnvPath}`);
+	const moltnetJson = readFileSync(moltnetPath, "utf8");
+	const agentEnvRaw = readFileSync(agentEnvPath, "utf8");
+	if (moltnetJson.trim() === "") throw new Error(`Agent configuration is empty: ${moltnetPath}`);
+	const gitconfigPath = path.join(agentDir, "gitconfig");
+	const gitconfig = existsSync(gitconfigPath) ? readFileSync(gitconfigPath, "utf8") : null;
+	const sshDir = path.join(agentDir, "ssh");
+	const sshPrivateKey = existsSync(path.join(sshDir, "id_ed25519")) ? readFileSync(path.join(sshDir, "id_ed25519"), "utf8") : null;
+	const sshPublicKey = existsSync(path.join(sshDir, "id_ed25519.pub")) ? readFileSync(path.join(sshDir, "id_ed25519.pub"), "utf8") : null;
+	const allowedSigners = existsSync(path.join(sshDir, "allowed_signers")) ? readFileSync(path.join(sshDir, "allowed_signers"), "utf8") : null;
+	let githubAppPem = null;
+	let githubAppPemFilename = null;
+	const pemPath = (moltnetJson ? JSON.parse(moltnetJson) : null)?.github?.private_key_path;
+	if (pemPath) if (!existsSync(pemPath)) onDiagnostic?.({
+		event: "vm.credentials.github_key_missing",
+		level: "warning",
+		credentialMode: mode,
+		message: `github.private_key_path not found at ${pemPath}; moltnet github token will fail inside the guest`
+	});
+	else {
+		githubAppPem = readFileSync(pemPath, "utf8");
+		githubAppPemFilename = path.basename(pemPath);
+	}
+	return {
+		moltnetJson,
+		agentEnvRaw,
+		providerAuthJson,
+		agentEnv: parseEnv(agentEnvRaw),
+		gitconfig,
+		sshPrivateKey,
+		sshPublicKey,
+		allowedSigners,
+		githubAppPem,
+		githubAppPemFilename
+	};
+}
+/**
+* Apply agent env vars to the host process, mirroring `moltnet start`.
+* Resolves relative paths (e.g. GIT_CONFIG_GLOBAL) against the repo root.
+*/
+function activateAgentEnv(agentEnv, repoRoot) {
+	for (const [k, v] of Object.entries(agentEnv)) {
+		if (v === void 0 || v === null || v === "") continue;
+		let resolved = v;
+		if (k === "GIT_CONFIG_GLOBAL" && !path.isAbsolute(v)) resolved = path.join(repoRoot, v);
+		process.env[k] = resolved;
+	}
+}
+var BASE_ALLOWED_HOSTS = [
+	"api.openai.com",
+	"*.openai.com",
+	"chat.openai.com",
+	"chatgpt.com",
+	"*.chatgpt.com",
+	"registry.npmjs.org",
+	"github.com",
+	"*.github.com",
+	"*.githubusercontent.com",
+	"proxy.golang.org",
+	"sum.golang.org",
+	"golang.org",
+	"storage.googleapis.com",
+	"*.googlesource.com"
+];
+var DEFAULT_MOLTNET_API_URL = "https://api.themolt.net";
+/**
+* Host environment names that may intentionally cross into a
+* host-authenticated guest. This local list is the authority boundary;
+* server-supplied runtime-profile `requiredEnv` cannot widen it.
+*/
+var HOST_AUTHENTICATED_GUEST_ENV_ALLOWLIST = new Set([
+	"ANTHROPIC_API_KEY",
+	"OPENAI_API_KEY",
+	"OPENAI_BASE_URL",
+	"AZURE_OPENAI_API_KEY",
+	"AZURE_OPENAI_ENDPOINT",
+	"AZURE_OPENAI_API_VERSION",
+	"GOOGLE_API_KEY",
+	"GEMINI_API_KEY",
+	"MISTRAL_API_KEY",
+	"GROQ_API_KEY",
+	"OPENROUTER_API_KEY",
+	"XAI_API_KEY",
+	"CEREBRAS_API_KEY",
+	"DEEPSEEK_API_KEY",
+	"OLLAMA_API_KEY",
+	"OLLAMA_BASE_URL",
+	"AWS_ACCESS_KEY_ID",
+	"AWS_SECRET_ACCESS_KEY",
+	"AWS_SESSION_TOKEN",
+	"AWS_REGION",
+	"AWS_DEFAULT_REGION",
+	"GITHUB_TOKEN",
+	"GH_TOKEN",
+	"LINEAR_API_KEY"
+]);
+var RESERVED_GUEST_ENVIRONMENT_NAMES = new Set([
+	"PATH",
+	"HOME",
+	"NODE_EXTRA_CA_CERTS",
+	"MOLTNET_GUEST_WORKSPACE",
+	"GIT_SSH",
+	"GIT_SSH_COMMAND",
+	"SSH_AUTH_SOCK"
+]);
+function isReservedGuestEnvironmentName(name) {
+	return name.startsWith("MOLTNET_") || name.startsWith("GIT_CONFIG_") || RESERVED_GUEST_ENVIRONMENT_NAMES.has(name);
+}
+var GuestEnvironmentBoundaryError = class extends Error {
+	constructor(refusedNames) {
+		super(`Guest credential boundary refuses runtime-controlled environment variables: ${refusedNames.join(", ")}. Remove them from the runtime profile; MoltNet operations use the trusted host-side Agent.`);
+		this.refusedNames = refusedNames;
+		this.name = "GuestEnvironmentBoundaryError";
+	}
+};
+function assertGuestEnvironmentBoundary(options) {
+	const refusedForwardEnv = (options.forwardEnv ?? []).filter((name) => isReservedGuestEnvironmentName(name) || options.guestCredentialMode === "host-authenticated" && !HOST_AUTHENTICATED_GUEST_ENV_ALLOWLIST.has(name));
+	const refusedSandboxEnv = Object.keys(options.sandboxEnv ?? {}).filter(isReservedGuestEnvironmentName);
+	const refused = [...new Set([...refusedForwardEnv, ...refusedSandboxEnv])].sort();
+	if (refused.length > 0) throw new GuestEnvironmentBoundaryError(refused);
+}
+/** @deprecated Prefer assertGuestEnvironmentBoundary for mode-aware checks. */
+function assertHostAuthenticatedGuestEnvironment(options) {
+	assertGuestEnvironmentBoundary({
+		guestCredentialMode: "host-authenticated",
+		...options
+	});
+}
+/**
+* Return whether two Gondolin hostname globs can match at least one common
+* string. Each `*` is an arbitrary substring, so this walks the product of the
+* two small glob automata instead of relying on exact-string comparisons.
+*/
+function hostnamePatternsOverlap(left, right) {
+	const a = left.trim().toLowerCase();
+	const b = right.trim().toLowerCase();
+	if (!a || !b) return false;
+	const pending = [[0, 0]];
+	const visited = /* @__PURE__ */ new Set();
+	while (pending.length > 0) {
+		const next = pending.pop();
+		if (!next) continue;
+		const [aIndex, bIndex] = next;
+		const state = `${aIndex}:${bIndex}`;
+		if (visited.has(state)) continue;
+		visited.add(state);
+		if (aIndex === a.length && bIndex === b.length) return true;
+		const aChar = a[aIndex];
+		const bChar = b[bIndex];
+		if (aChar === "*") pending.push([aIndex + 1, bIndex]);
+		if (bChar === "*") pending.push([aIndex, bIndex + 1]);
+		if (aChar !== void 0 && bChar !== void 0 && (aChar === "*" || bChar === "*" || aChar === bChar)) pending.push([aChar === "*" ? aIndex : aIndex + 1, bChar === "*" ? bIndex : bIndex + 1]);
+	}
+	return false;
+}
+function assertInternalHostsDoNotOverlapProtectedHosts(internalHosts, protectedHosts) {
+	for (const internalHost of internalHosts) {
+		const protectedHost = protectedHosts.find((candidate) => hostnamePatternsOverlap(internalHost, candidate));
+		if (protectedHost) throw new Error(`sandbox.network.allowedInternalHosts pattern "${internalHost}" overlaps external-only host pattern "${protectedHost}"`);
+	}
+}
+/**
+* Run a shell command in the guest and throw if it fails. Mirror of
+* `run()` in `snapshot.ts` for the resume-side hook chain — every
+* setup step is essential to a healthy session, so a silent non-zero
+* exit (e.g. a mount that fails into the FUSE write path, or a
+* consumer-provided resume command that fails to install pnpm) must
+* surface immediately rather than fall through to cryptic agent
+* errors later.
+*/
+async function vmRun(vm, label, command, signal) {
+	const wrapped = `set -eu\nset -o pipefail\n${command}`;
+	throwIfAborted(signal, `resume step "${label}"`);
+	const r = await vm.exec([
+		"sh",
+		"-c",
+		wrapped
+	], { signal });
+	if (r.exitCode !== 0) {
+		const tail = [r.stderr, r.stdout].filter(Boolean).join("\n").slice(-800);
+		throw new Error(`resume step "${label}" failed (exit ${r.exitCode}):\n${tail}`);
+	}
+}
+function nonErrorMessage(err) {
+	if (typeof err === "string") return err;
+	try {
+		return JSON.stringify(err) ?? "unknown error";
+	} catch {
+		return "unknown error";
+	}
+}
+/**
+* Resume a VM from a checkpoint, inject credentials, configure egress +
+* TLS. Returns the managed VM handle.
+*/
+async function resumeVm(config) {
+	throwIfAborted(config.signal, "VM resume");
+	const agentDir = resolveVmAgentDir(config);
+	const guestWorkspace = path.resolve(config.mountPath);
+	const guestCredentialMode = config.guestCredentialMode ?? "guest-config";
+	if (guestCredentialMode === "guest-config" && !existsSync(agentDir)) throw new Error(`Agent directory not found: ${agentDir}. Run: moltnet register --name ${config.agentName}`);
+	assertGuestEnvironmentBoundary({
+		guestCredentialMode,
+		forwardEnv: config.forwardEnv,
+		sandboxEnv: config.sandboxConfig?.env
+	});
+	config.onDiagnostic?.({
+		event: "vm.credentials.mode",
+		level: "info",
+		credentialMode: guestCredentialMode,
+		message: guestCredentialMode === "host-authenticated" ? "MoltNet agent files and non-allowlisted host environment variables are withheld from the guest" : "The complete MoltNet agent configuration is available to the guest"
+	});
+	const creds = loadCredentials(agentDir, guestCredentialMode, config.onDiagnostic, config.providerAuth);
+	const configuredApiUrl = creds.moltnetJson ? JSON.parse(creds.moltnetJson).endpoints.api : void 0;
+	const apiHost = new URL(configuredApiUrl ?? process.env.MOLTNET_API_URL ?? DEFAULT_MOLTNET_API_URL).hostname;
+	const runtimeAllowedHosts = config.sandboxConfig?.network?.allowedHosts ?? [];
+	const runtimeAllowedInternalHosts = config.sandboxConfig?.network?.allowedInternalHosts ?? [];
+	const protectedExternalHosts = [...new Set([
+		...BASE_ALLOWED_HOSTS,
+		apiHost,
+		...config.extraAllowedHosts ?? []
+	])];
+	assertInternalHostsDoNotOverlapProtectedHosts(runtimeAllowedInternalHosts, protectedExternalHosts);
+	const { httpHooks, env: secretEnv } = createHttpHooks({
+		allowedHosts: [...new Set([...protectedExternalHosts, ...runtimeAllowedHosts])],
+		allowedInternalHosts: runtimeAllowedInternalHosts
+	});
+	const vmAgentDir = `/home/agent/.moltnet/${config.agentName}`;
+	const vmAgentEnv = {};
+	for (const [k, v] of Object.entries(creds.agentEnv)) {
+		if (v === void 0 || v === "") continue;
+		if (k === "GIT_CONFIG_GLOBAL") vmAgentEnv[k] = `${vmAgentDir}/gitconfig`;
+		else if (k.endsWith("_PRIVATE_KEY_PATH")) vmAgentEnv[k] = `${vmAgentDir}/${path.basename(v)}`;
+		else vmAgentEnv[k] = v;
+	}
+	if (creds.moltnetJson) vmAgentEnv.MOLTNET_CREDENTIALS_PATH = `${vmAgentDir}/moltnet.json`;
+	const vfsConfig = resolveVfsShadowConfig(config.sandboxConfig);
+	let workspaceProvider = new RealFSProvider(config.mountPath);
+	workspaceProvider = new ShadowProvider(workspaceProvider, {
+		shouldShadow: ({ path: shadowPath }) => shouldShadowNodeModulesPath(shadowPath),
+		denySymlinkBypass: false,
+		tmpfs: new AutoParentMemoryProvider(),
+		writeMode: "tmpfs"
+	});
+	if (vfsConfig.mode !== "none") {
+		const predicate = createShadowPathPredicate(vfsConfig.patterns);
+		workspaceProvider = new ShadowProvider(workspaceProvider, {
+			shouldShadow: predicate,
+			writeMode: vfsConfig.mode
+		});
+	}
+	if (guestCredentialMode === "host-authenticated") workspaceProvider = new ShadowProvider(workspaceProvider, {
+		shouldShadow: ({ path: shadowPath }) => shadowPath.split("/").includes(".moltnet"),
+		denySymlinkBypass: true,
+		writeMode: "deny"
+	});
+	const forwardedEnv = {};
+	for (const name of config.forwardEnv ?? []) {
+		const value = process.env[name];
+		if (value === void 0 || value === "") continue;
+		forwardedEnv[name] = value;
+	}
+	const envOverrides = config.sandboxConfig?.env ?? {};
+	const vmEnv = {
+		...secretEnv,
+		...vmAgentEnv,
+		...forwardedEnv,
+		PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/lib/go/bin",
+		HOME: "/home/agent",
+		NODE_NO_WARNINGS: "1",
+		NODE_EXTRA_CA_CERTS: "/etc/ssl/certs/ca-certificates.crt",
+		...envOverrides,
+		MOLTNET_GUEST_WORKSPACE: guestWorkspace
+	};
+	const resources = config.sandboxConfig?.resources;
+	const workspaceMode = config.workspaceMode ?? "shared_mount";
+	const vm = await abortableResource({
+		promise: VmCheckpoint.load(config.checkpointPath).resume({
+			httpHooks,
+			env: vmEnv,
+			...resources?.memory && { memory: resources.memory },
+			...resources?.cpus && { cpus: resources.cpus },
+			vfs: { mounts: {
+				[guestWorkspace]: workspaceProvider,
+				[GUEST_TASK_CONTEXT_MOUNT]: new MemoryProvider()
+			} }
+		}),
+		signal: config.signal,
+		label: "VM resume",
+		cleanup: (resumedVm) => resumedVm.close(),
+		onCleanupError: (err) => {
+			const message = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`[vm] aborted resume late vm.close() failed: ${message}\n`);
+		}
+	});
+	try {
+		await vmRun(vm, "TLS certificates", `
+    cp /etc/gondolin/mitm/ca.crt /usr/local/share/ca-certificates/gondolin-mitm.crt
+    update-ca-certificates 2>/dev/null
+    cat /etc/gondolin/mitm/ca.crt >> /etc/ssl/certs/ca-certificates.crt
+  `, config.signal);
+		await vmRun(vm, "DNS resolvers", `printf 'nameserver 8.8.8.8\\nnameserver 1.1.1.1\\n' > /etc/resolv.conf`, config.signal);
+		await vmRun(vm, "git safe.directory", `git config --system --add safe.directory '*'`, config.signal);
+		for (const [i, entry] of (config.sandboxConfig?.resumeCommands ?? []).entries()) {
+			if (!shouldRunResumeCommand(entry, { workspaceMode })) continue;
+			const { run, retries, backoffMs } = typeof entry === "string" ? {
+				run: entry,
+				retries: 0,
+				backoffMs: 2e3
+			} : {
+				run: entry.run,
+				retries: entry.retries ?? 0,
+				backoffMs: entry.retryBackoffMs ?? 2e3
+			};
+			const label = `resumeCommands[${i}]`;
+			let lastErr;
+			for (let attempt = 0; attempt <= retries; attempt++) try {
+				await vmRun(vm, label, run, config.signal);
+				lastErr = void 0;
+				break;
+			} catch (err) {
+				lastErr = err;
+				if (attempt === retries) break;
+				await delay((attempt + 1) * backoffMs, config.signal, label);
+			}
+			if (lastErr) throw lastErr instanceof Error ? lastErr : new Error(nonErrorMessage(lastErr));
+		}
+		const vmSshDir = `${vmAgentDir}/ssh`;
+		const hasAgentFiles = guestCredentialMode === "guest-config";
+		const providerAuthDir = config.providerAuth ? path.posix.dirname(config.providerAuth.guestPath) : null;
+		const guestDirs = [...hasAgentFiles ? [`${vmAgentDir}/ssh`] : [], ...providerAuthDir ? [providerAuthDir] : []];
+		if (guestDirs.length > 0) await vm.exec(`mkdir -p ${guestDirs.join(" ")}`, { signal: config.signal });
+		if (creds.providerAuthJson !== null && config.providerAuth) await vm.fs.writeFile(config.providerAuth.guestPath, creds.providerAuthJson, {
+			mode: 384,
+			signal: config.signal
+		});
+		if (hasAgentFiles) {
+			const vmMoltnetJson = rewriteMoltnetJsonPaths(creds.moltnetJson, vmAgentDir, vmSshDir, creds.githubAppPemFilename);
+			await vm.fs.writeFile(`${vmAgentDir}/moltnet.json`, vmMoltnetJson, {
+				mode: 384,
+				signal: config.signal
+			});
+			await vm.fs.writeFile(`${vmAgentDir}/env`, creds.agentEnvRaw, {
+				mode: 384,
+				signal: config.signal
+			});
+			if (creds.gitconfig) {
+				const vmGitconfig = rewriteGitconfigPaths(creds.gitconfig, vmSshDir, vmAgentDir);
+				await vm.fs.writeFile(`${vmAgentDir}/gitconfig`, vmGitconfig, {
+					mode: 420,
+					signal: config.signal
+				});
+			}
+			if (creds.sshPrivateKey) await vm.fs.writeFile(`${vmSshDir}/id_ed25519`, creds.sshPrivateKey, {
+				mode: 384,
+				signal: config.signal
+			});
+			if (creds.sshPublicKey) await vm.fs.writeFile(`${vmSshDir}/id_ed25519.pub`, creds.sshPublicKey, {
+				mode: 420,
+				signal: config.signal
+			});
+			if (creds.allowedSigners) await vm.fs.writeFile(`${vmSshDir}/allowed_signers`, creds.allowedSigners, {
+				mode: 420,
+				signal: config.signal
+			});
+			if (creds.githubAppPem && creds.githubAppPemFilename) await vm.fs.writeFile(`${vmAgentDir}/${creds.githubAppPemFilename}`, creds.githubAppPem, {
+				mode: 384,
+				signal: config.signal
+			});
+		}
+		await vm.exec(hasAgentFiles ? "chown -R agent:agent /home/agent/.pi /home/agent/.moltnet" : "chown -R agent:agent /home/agent/.pi", { signal: config.signal });
+		return {
+			vm,
+			credentials: creds,
+			mountPath: config.mountPath,
+			guestWorkspace,
+			agentDir
+		};
+	} catch (err) {
+		try {
+			await vm.close();
+		} catch (closeErr) {
+			const m = closeErr instanceof Error ? closeErr.message : String(closeErr);
+			process.stderr.write(`[vm] post-throw vm.close() failed: ${m}\n`);
+		}
+		throw err;
+	}
+}
+/**
+* Rewrite host-absolute paths inside an agent gitconfig to VM-local
+* equivalents before injecting it into the guest.
+*
+* Two rewrites:
+*   - `signingKey = <host path>`  → `<vmSshDir>/id_ed25519`
+*   - `... credential-helper --credentials <host moltnet.json>`
+*                                 → `<vmAgentDir>/moltnet.json`
+*
+* The credential-helper line is generated host-side by `moltnet github setup`
+* with a host-absolute `--credentials` path; inside the guest that path is
+* invalid, so it must point at the VM-side moltnet.json. The `insteadOf`
+* rewrite rule and every other line are workspace-independent and pass through
+* unchanged. A gitconfig without a credential helper is rewritten only for
+* `signingKey`.
+*
+* This is the single source of truth for git push auth in the guest: the
+* injected gitconfig carries the tokenless mint-on-demand helper, so the VM
+* no longer hand-rolls a credential-helper script or runs an imperative
+* `git config --global ... insteadOf` against the guest $HOME.
+*/
+function rewriteGitconfigPaths(gitconfig, vmSshDir, vmAgentDir) {
+	return gitconfig.replace(/signingKey\s*=\s*.+/g, `signingKey = ${vmSshDir}/id_ed25519`).replace(/(moltnet github credential-helper --credentials )\S+/g, `$1${vmAgentDir}/moltnet.json`);
+}
+/**
+* Rewrite host-absolute paths inside moltnet.json to VM-local equivalents.
+*
+* Fields rewritten:
+*   ssh.private_key_path  → <vmSshDir>/<basename of original>
+*   ssh.public_key_path   → <vmSshDir>/<basename of original>
+*   git.config_path       → <vmAgentDir>/gitconfig
+*   github.private_key_path → <vmAgentDir>/<pemFilename>  (if present)
+*
+* All other fields are passed through unchanged.
+* Throws if moltnetJson is not valid JSON — callers must not inject a broken
+* moltnet.json into the guest.
+*/
+function rewriteMoltnetJsonPaths(moltnetJson, vmAgentDir, vmSshDir, githubAppPemFilename) {
+	const config = JSON.parse(moltnetJson);
+	if (config.ssh && typeof config.ssh === "object") {
+		const ssh = config.ssh;
+		const origPrivate = typeof ssh.private_key_path === "string" ? ssh.private_key_path : null;
+		const origPublic = typeof ssh.public_key_path === "string" ? ssh.public_key_path : null;
+		config.ssh = {
+			...ssh,
+			...origPrivate !== null && { private_key_path: `${vmSshDir}/${path.basename(origPrivate)}` },
+			...origPublic !== null && { public_key_path: `${vmSshDir}/${path.basename(origPublic)}` }
+		};
+	}
+	if (config.git && typeof config.git === "object") {
+		const git = { ...config.git };
+		git.config_path = `${vmAgentDir}/gitconfig`;
+		config.git = git;
+	}
+	if (githubAppPemFilename && config.github && typeof config.github === "object") {
+		const github = { ...config.github };
+		github.private_key_path = `${vmAgentDir}/${githubAppPemFilename}`;
+		config.github = github;
+	}
+	return JSON.stringify(config);
+}
+//#endregion
+export { AutoParentMemoryProvider, GONDOLIN_BASE_EXECUTABLES, GUEST_TASK_CONTEXT_MOUNT, GUEST_TASK_SKILLS_MOUNT, GuestEnvironmentBoundaryError, abortableResource, activateAgentEnv, assertGuestEnvironmentBoundary, assertHostAuthenticatedGuestEnvironment, delay, ensureSnapshot, findMainWorktree, isResolvedPathInsideRoot, loadCredentials, resolveVfsShadowConfig, resolveVmAgentDir, resumeVm, rewriteGitconfigPaths, rewriteMoltnetJsonPaths, shouldRunResumeCommand, shouldShadowNodeModulesPath, throwIfAborted };