zidane 7.2.5 → 8.0.4

package/dist/{contexts-CRE9pw07.js → contexts-d7UolYot.js}

@@ -1,10 +1,19 @@
+import { a as loginShell, c as DEFAULT_MAX_OUTPUT_BUFFER, f as outputExceededMessage, i as localTerminalProcess, l as appendCapped, o as ptyChildProcess, r as hasLocalPty, s as spawnLocalPty, t as TERMINAL_ENV } from "./local-terminal-D8QThwo_.js";
 import { t as lazyAsync } from "./lazy-DLOurOC_.js";
-import { n as globLiteralPrefix, t as globFilesLocal } from "./glob-DluQFSw1.js";
-import { a as outputExceededMessage, n as appendCapped, t as DEFAULT_MAX_OUTPUT_BUFFER } from "./output-cap-C9zukcCj.js";
-import { delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { accessSync, constants, createWriteStream, realpathSync, statSync } from "node:fs";
+import { accessSync, constants, createWriteStream, openSync, realpathSync, statSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { mkdir, readFile, readdir, realpath, stat, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+//#region src/contexts/types.ts
+/**
+* Effective {@link DetachedTasksCapability} of a context, with the
+* backward-compatible inference for contexts that predate the field.
+*/
+function resolveDetachedTasksCapability(context) {
+	return context.capabilities.detachedTasks ?? (context.execBackground ? "process-lifetime" : "none");
+}
+//#endregion
 //#region src/contexts/isolation.ts
 /**
 * Only `/usr/bin/sandbox-exec` is trusted — never a `PATH` lookup — so a
@@ -78,7 +87,7 @@ function isolationAvailability(platform = process.platform, env = process.env) {
 		executable: bwrap
 	} : {
 		ok: false,
-		reason: "bwrap (bubblewrap) is not installed — install it with your package manager (e.g. `apt install bubblewrap`)"
+		reason: "bwrap (bubblewrap) is not installed. Install it with your package manager (e.g. `apt install bubblewrap`)"
 	};
 }
 /** Expand a leading `~` / `~/` to `home`. Other paths returned unchanged. */
@@ -488,7 +497,7 @@ function unavailableResult(reason) {
 	};
 }
 //#endregion
-//#region src/contexts/process.ts
+//#region src/contexts/process-state.ts
 /**
 * Lazily load `node:child_process`'s `spawn` (memoized after first use).
 *
@@ -512,18 +521,15 @@ const loadSpawn = lazyAsync(async () => (await import("node:child_process")).spa
 */
 const SUPPORTS_PROCESS_GROUPS = process.platform !== "win32";
 /**
-* Default cap on captured stdout / stderr per child. Matches the
-* pre-fix `child_process.exec` setting so existing callers see the
-* same buffer envelope. Output beyond this is truncated and a
-* marker is appended to stderr.
-*/
-/**
-* How long `destroy()` waits for a SIGTERM'd background task to settle
-* before escalating to SIGKILL and abandoning the wait. Matches the MCP
-* connection's default `closeTimeout` so `agent.destroy()` stays bounded
-* by a single grace period regardless of which leg is slowest.
+* Background tasks on a PTY see a terminal where they used to see pipes:
+* keep pagers and git's credential prompt from waiting on input nobody
+* types. The command's own env still wins.
 */
-const DESTROY_SIGTERM_GRACE_MS = 5e3;
+const TERMINAL_TASK_ENV = {
+	PAGER: "cat",
+	GIT_PAGER: "cat",
+	GIT_TERMINAL_PROMPT: "0"
+};
 /**
 * How long an `exec` kill (timeout / abort / output-overflow) waits after
 * SIGTERM before escalating the process group to SIGKILL. A child that
@@ -559,7 +565,7 @@ const EXIT_PIPE_DRAIN_GRACE_MS = 1500;
 */
 const TASK_ID_RE = /^[a-z][\w-]*$/i;
 function assertSafeTaskId(taskId) {
-	if (!TASK_ID_RE.test(taskId)) throw new Error(`Invalid task id "${taskId}" — must match ${TASK_ID_RE}.`);
+	if (!TASK_ID_RE.test(taskId)) throw new Error(`Invalid task id "${taskId}": it must match ${TASK_ID_RE}.`);
 }
 /**
 * Format `date` as `YYYYMMDD-HHMMSS-mmm` in UTC.
@@ -580,12 +586,11 @@ function pickEnv(env, keys) {
 	for (const key of keys) if (env[key] !== void 0) out[key] = env[key];
 	return out;
 }
-function createProcessContext(config) {
-	let counter = 0;
+function createProcessState(config) {
 	const handles = /* @__PURE__ */ new Map();
 	const defaultCwd = config?.cwd ?? process.cwd();
 	const defaultEnv = config?.env;
-	const destroyGraceMs = config?.destroyGraceMs ?? DESTROY_SIGTERM_GRACE_MS;
+	const destroyGraceMs = config?.destroyGraceMs ?? 5e3;
 	const baseEnv = config?.inheritEnv === false ? pickEnv(process.env, [
 		"PATH",
 		"HOME",
@@ -600,68 +605,6 @@ function createProcessContext(config) {
 	const isolation = config?.isolation;
 	const isolationState = isolation ? isolationAvailability() : void 0;
 	/**
-	* `{ file, args }` for `/bin/sh -c command`, wrapped in the sandbox when
-	* isolation is on. Callers check `isolationState.ok` first (the three
-	* shell entry points return `unavailableResult` / throw before spawning).
-	*/
-	function shellCommand(command) {
-		if (isolation && isolationState?.ok) return wrapCommand(isolationState.backend, isolationState.executable, isolation, command);
-		return {
-			file: "/bin/sh",
-			args: ["-c", command]
-		};
-	}
-	/** Failure result when isolation was requested but cannot be enforced; `undefined` = proceed. */
-	function isolationBlocker() {
-		return isolationState && !isolationState.ok ? unavailableResult(isolationState.reason) : void 0;
-	}
-	/**
-	* Resolve `path` against the handle cwd and, when a `workspaceRoot` is
-	* configured, reject anything that escapes it. Uses `realpath` on the
-	* nearest existing ancestor so symlink escapes (and `..`) are caught for
-	* both existing and not-yet-created targets.
-	*/
-	async function resolveContained(handle, path) {
-		const full = resolve(handle.cwd, path);
-		if (workspaceRoot === void 0) return full;
-		const canonical = await canonicalizeForCheck(full);
-		const canonicalRoot = await realpath(workspaceRoot).catch(() => workspaceRoot);
-		if (!isWithinRoot(canonicalRoot, canonical)) throw new Error(`Path escapes the workspace root: ${path} (resolved outside ${canonicalRoot})`);
-		return full;
-	}
-	/**
-	* Canonicalize the deepest existing ancestor of `full` to defeat symlink
-	* escapes; the non-existent tail (for writes) is appended back verbatim.
-	*/
-	async function canonicalizeForCheck(full) {
-		let existing = full;
-		const tail = [];
-		while (true) try {
-			existing = await realpath(existing);
-			break;
-		} catch {
-			const parent = dirname(existing);
-			if (parent === existing) {
-				existing = parent;
-				break;
-			}
-			tail.unshift(relative(parent, existing));
-			existing = parent;
-		}
-		return tail.length ? resolve(existing, ...tail) : existing;
-	}
-	/**
-	* In-process counterpart of the sandbox's write policy: `writeFile` (and
-	* so the `write_file` / `edit` tools) may only target `isolation.writableRoots`.
-	* Reads are deliberately unrestricted — same boundary the kernel enforces
-	* for shell commands, so the two never disagree about where writes land.
-	*/
-	async function assertWritable(full, path) {
-		if (!isolation) return;
-		const canonical = await canonicalizeForCheck(full);
-		if (!isolation.writableRoots.some((root) => isWithinRoot(root, canonical))) throw new Error(`[sandbox] write denied: ${path} is outside the writable roots (${isolation.writableRoots.join(", ")}). Ask the user to add it under Settings → "Sandbox writable paths" or turn off "Sandbox shell commands".`);
-	}
-	/**
 	* Per-context background-task registry. Entries live for the context's
 	* lifetime — even after the child exits — so the model can read output
 	* of completed tasks until `destroy()` tears everything down. Kept as
@@ -669,7 +612,6 @@ function createProcessContext(config) {
 	* abstraction. The state and the operations on it live inline.
 	*/
 	const tasks = /* @__PURE__ */ new Map();
-	let taskCounter = 0;
 	/**
 	* Per-context UTC timestamp segment baked into every background task's
 	* log filename. Same `taskCounter` value across two contexts (e.g. a
@@ -711,7 +653,25 @@ function createProcessContext(config) {
 	*/
 	/** Live `execStream` children → owning handle id. See `exitHandler`. */
 	const streamChildren = /* @__PURE__ */ new Map();
-	let exitHandlerRegistered = false;
+	const s = {
+		config,
+		counter: 0,
+		handles,
+		defaultCwd,
+		defaultEnv,
+		destroyGraceMs,
+		baseEnv,
+		workspaceRoot,
+		isolation,
+		isolationState,
+		tasks,
+		taskCounter: 0,
+		contextTimestamp,
+		streamChildren,
+		exitHandlerRegistered: false,
+		exitHandler: () => {},
+		registerExitHandler: () => {}
+	};
 	const exitHandler = () => {
 		for (const task of tasks.values()) {
 			if (task.status !== "running") continue;
@@ -725,156 +685,679 @@ function createProcessContext(config) {
 		for (const child of streamChildren.keys()) killProcessGroup(child, "SIGTERM");
 	};
 	const registerExitHandler = () => {
-		if (!exitHandlerRegistered) {
+		if (!s.exitHandlerRegistered) {
 			process.on("exit", exitHandler);
-			exitHandlerRegistered = true;
+			s.exitHandlerRegistered = true;
 		}
 	};
+	s.exitHandler = exitHandler;
+	s.registerExitHandler = registerExitHandler;
+	return s;
+}
+/**
+* Send `signal` to the child's whole process group. Falls back to a
+* single-process kill on Windows (no POSIX process groups). Shared
+* across the foreground `exec` path, the background spawn / kill
+* paths, and the shutdown-time orphan reaper — keeping one definition
+* so the kill semantics can't drift between them.
+*/
+function killProcessGroup(child, signal) {
+	const pid = child?.pid;
+	if (pid === void 0) return;
+	try {
+		if (SUPPORTS_PROCESS_GROUPS) process.kill(-pid, signal);
+		else process.kill(pid, signal);
+	} catch {}
+}
+/**
+* Project a `TaskState` to the `TaskEntry` shape `listBackground` and
+* `reassignBackgroundTasks` return. Single helper keeps the shape
+* consistent across both call sites (and a future addition of fields
+* to `TaskEntry` only needs to land here).
+*/
+function stateToTaskEntry(state) {
 	return {
-		type: "process",
-		capabilities: {
-			shell: true,
-			filesystem: true,
-			glob: true,
-			network: true,
-			gpu: false,
-			stream: true,
-			isolated: isolation !== void 0 && isolationState?.ok === true,
-			detachedTasks: "process-lifetime"
-		},
-		async spawn(overrides) {
-			const id = `process-${++counter}`;
-			const cwd = overrides?.cwd ?? defaultCwd;
-			let needsCreate = false;
-			try {
-				await stat(cwd);
-			} catch (err) {
-				needsCreate = err?.code === "ENOENT";
+		taskId: state.taskId,
+		pid: state.pid,
+		command: state.command,
+		cwd: state.cwd,
+		startedAt: state.startedAt,
+		...state.endedAt !== void 0 ? { endedAt: state.endedAt } : {},
+		outputPath: state.outputPath,
+		status: state.status,
+		...state.exitCode !== void 0 ? { exitCode: state.exitCode } : {},
+		...state.signal ? { signal: state.signal } : {},
+		bytesWritten: state.bytesWritten
+	};
+}
+/**
+* Project a settled `TaskState` to the `TaskExitInfo` shape `settle()`
+* fires from `onExit` and `killBackground` returns on the
+* cached-exit path. Pre-condition: `state.status !== 'running'`
+* (callers gate on this).
+*/
+function stateToTaskExitInfo(state) {
+	return {
+		taskId: state.taskId,
+		status: state.status,
+		exitCode: state.exitCode ?? 0,
+		...state.signal ? { signal: state.signal } : {},
+		outputPath: state.outputPath,
+		durationMs: (state.endedAt ?? Date.now()) - state.startedAt,
+		command: state.command
+	};
+}
+//#endregion
+//#region src/contexts/process-background.ts
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+/**
+* The log's fd: a new file (exclusive), never through a symlink planted at
+* its path. A name collision keeps the old append behavior on the existing
+* regular file (still not following a link), as the comment at the call says.
+*/
+function openTaskLog(path) {
+	const write = constants.O_WRONLY | constants.O_APPEND | NO_FOLLOW;
+	try {
+		return openSync(path, write | constants.O_CREAT | constants.O_EXCL, 384);
+	} catch (err) {
+		if (err.code !== "EEXIST") throw err;
+		return openSync(path, write);
+	}
+}
+function processBackgroundMethods(s, sh) {
+	const { baseEnv, defaultEnv, tasks, contextTimestamp, registerExitHandler } = s;
+	const { shellCommand, isolationBlocker, spawnTerminalTask } = sh;
+	return { async execBackground(handle, command, options) {
+		const cwd = options.cwd ? resolve(handle.cwd, options.cwd) : handle.cwd;
+		const spawnChild = await loadSpawn();
+		const blocked = isolationBlocker();
+		if (blocked) throw new Error(blocked.stderr);
+		await mkdir(options.outputDir, { recursive: true });
+		const taskId = `bash_${++s.taskCounter}`;
+		assertSafeTaskId(taskId);
+		const outputPath = resolve(options.outputDir, `${taskId}.${contextTimestamp}.log`);
+		registerExitHandler();
+		const outputStream = createWriteStream(outputPath, { fd: openTaskLog(outputPath) });
+		outputStream.on("error", (err) => {
+			if (process.env.ZIDANE_DEBUG) process.stderr.write(`[zidane/contexts] task ${taskId} log stream error: ${err.message}\n`);
+		});
+		const shell = shellCommand(command);
+		const tty = options.terminal && hasLocalPty() ? options.terminal : void 0;
+		const child = tty ? spawnTerminalTask([shell.file, ...shell.args], cwd, {
+			...TERMINAL_TASK_ENV,
+			...options.env
+		}, tty) : spawnChild(shell.file, shell.args, {
+			cwd,
+			env: {
+				...baseEnv,
+				...defaultEnv,
+				...options.env
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			detached: SUPPORTS_PROCESS_GROUPS
+		});
+		const state = {
+			taskId,
+			handleId: handle.id,
+			pid: child.pid ?? -1,
+			command,
+			cwd,
+			startedAt: Date.now(),
+			outputPath,
+			outputStream,
+			child,
+			status: "running",
+			bytesWritten: 0,
+			settled: false,
+			onExit: options.onExit,
+			onStall: options.onStall,
+			exitWatchers: []
+		};
+		tasks.set(taskId, state);
+		const maxOutputBytes = typeof options.maxOutputBytes === "number" && options.maxOutputBytes > 0 ? options.maxOutputBytes : void 0;
+		let droppedBytes = 0;
+		let capExhausted = false;
+		const stallTimeoutMs = typeof options.stallTimeoutMs === "number" && options.stallTimeoutMs > 0 ? options.stallTimeoutMs : void 0;
+		let stallTimer;
+		let lastOutputAt = Date.now();
+		const armStallTimer = () => {
+			if (!stallTimeoutMs || !state.onStall) return;
+			if (stallTimer) clearTimeout(stallTimer);
+			stallTimer = setTimeout(() => {
+				stallTimer = void 0;
+				if (state.settled) return;
+				try {
+					state.onStall?.({
+						taskId,
+						command,
+						outputPath,
+						stalledForMs: Date.now() - lastOutputAt,
+						bytesWritten: state.bytesWritten
+					});
+				} catch (err) {
+					if (process.env.ZIDANE_DEBUG) process.stderr.write(`[zidane/contexts] task ${taskId} onStall threw: ${err instanceof Error ? err.message : String(err)}\n`);
+				}
+			}, stallTimeoutMs);
+			stallTimer.unref?.();
+		};
+		const clearStallTimer = () => {
+			if (stallTimer) {
+				clearTimeout(stallTimer);
+				stallTimer = void 0;
 			}
-			if (needsCreate) await mkdir(cwd, { recursive: true });
-			const handle = {
-				id,
-				type: "process",
-				cwd
+		};
+		armStallTimer();
+		const appendChunk = (chunk) => {
+			state.bytesWritten += chunk.length;
+			lastOutputAt = Date.now();
+			armStallTimer();
+			if (maxOutputBytes !== void 0) {
+				const onDisk = state.bytesWritten - droppedBytes - chunk.length;
+				if (capExhausted || onDisk >= maxOutputBytes) {
+					capExhausted = true;
+					droppedBytes += chunk.length;
+					return;
+				}
+				const room = maxOutputBytes - onDisk;
+				if (chunk.length > room) {
+					capExhausted = true;
+					let end = room;
+					while (end > 0 && (chunk[end] & 192) === 128) end--;
+					droppedBytes += chunk.length - end;
+					if (end > 0) outputStream.write(chunk.subarray(0, end));
+					return;
+				}
+			}
+			outputStream.write(chunk);
+		};
+		child.stdout?.on("data", (chunk) => appendChunk(chunk));
+		child.stderr?.on("data", (chunk) => appendChunk(chunk));
+		const settle = (cause, code, signal, errMessage) => {
+			if (state.settled) return;
+			state.settled = true;
+			clearStallTimer();
+			state.endedAt = Date.now();
+			const status = signal === "SIGTERM" || state.killRequested ? "killed" : "exited";
+			const exitCode = code !== null ? code : signal === "SIGTERM" ? 143 : signal ? 128 : 1;
+			state.status = status;
+			state.exitCode = exitCode;
+			if (signal) state.signal = signal;
+			if (errMessage) try {
+				outputStream.write(`\n${errMessage}\n`);
+			} catch {}
+			if (droppedBytes > 0) try {
+				outputStream.write(`\n<output-truncated bytes-dropped="${droppedBytes}"/>\n`);
+			} catch {}
+			outputStream.end(() => {
+				const info = stateToTaskExitInfo(state);
+				for (const callback of [state.onExit, ...state.exitWatchers.splice(0)]) try {
+					callback?.(info);
+				} catch (err) {
+					if (process.env.ZIDANE_DEBUG) process.stderr.write(`[zidane/contexts] task ${taskId} onExit threw: ${err instanceof Error ? err.message : String(err)}\n`);
+				}
+			});
+			state.child = void 0;
+			state.outputStream = void 0;
+		};
+		child.on("close", (code, signal) => settle("close", code, signal));
+		child.on("error", (err) => settle("error", null, null, `[spawn error] ${err.message}`));
+		child.on("exit", (code, signal) => {
+			setTimeout(() => {
+				if (state.settled) return;
+				child.stdout?.destroy();
+				child.stderr?.destroy();
+				settle("close", code, signal);
+			}, EXIT_PIPE_DRAIN_GRACE_MS).unref?.();
+		});
+		return {
+			taskId,
+			pid: state.pid,
+			outputPath,
+			...tty ? { terminal: true } : {}
+		};
+	} };
+}
+//#endregion
+//#region src/contexts/process-exec.ts
+function processExecMethods(s, sh) {
+	const { config, baseEnv, defaultEnv, isolation } = s;
+	const { shellCommand, isolationBlocker } = sh;
+	return { async exec(handle, command, options) {
+		const cwd = options?.cwd ? resolve(handle.cwd, options.cwd) : handle.cwd;
+		if (options?.signal?.aborted) return {
+			stdout: "",
+			stderr: "aborted by signal before spawn",
+			exitCode: 143
+		};
+		const blocked = isolationBlocker();
+		if (blocked) return blocked;
+		const timeoutMs = (options?.timeout ?? config?.limits?.timeout ?? 30) * 1e3;
+		const maxBuffer = DEFAULT_MAX_OUTPUT_BUFFER;
+		const spawnChild = await loadSpawn();
+		return new Promise((resolveP) => {
+			const shell = shellCommand(command);
+			const child = spawnChild(shell.file, shell.args, {
+				cwd,
+				env: {
+					...baseEnv,
+					...defaultEnv,
+					...options?.env
+				},
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				detached: SUPPORTS_PROCESS_GROUPS
+			});
+			const stdoutSlot = {
+				text: "",
+				bytes: 0
 			};
-			handles.set(id, handle);
-			return handle;
-		},
-		async exec(handle, command, options) {
-			const cwd = options?.cwd ? resolve(handle.cwd, options.cwd) : handle.cwd;
-			if (options?.signal?.aborted) return {
-				stdout: "",
-				stderr: "aborted by signal before spawn",
-				exitCode: 143
+			const stderrSlot = {
+				text: "",
+				bytes: 0
 			};
-			const blocked = isolationBlocker();
-			if (blocked) return blocked;
-			const timeoutMs = (options?.timeout ?? config?.limits?.timeout ?? 30) * 1e3;
-			const maxBuffer = DEFAULT_MAX_OUTPUT_BUFFER;
-			const spawnChild = await loadSpawn();
-			return new Promise((resolveP) => {
-				const shell = shellCommand(command);
-				const child = spawnChild(shell.file, shell.args, {
-					cwd,
-					env: {
-						...baseEnv,
-						...defaultEnv,
-						...options?.env
-					},
-					stdio: [
-						"ignore",
-						"pipe",
-						"pipe"
-					],
-					detached: SUPPORTS_PROCESS_GROUPS
-				});
-				const stdoutSlot = {
-					text: "",
-					bytes: 0
-				};
-				const stderrSlot = {
-					text: "",
-					bytes: 0
-				};
-				let bufferTruncated = false;
-				let timedOut = false;
-				let killedByAbort = false;
-				let settled = false;
-				const killWithEscalation = () => {
-					killProcessGroup(child, "SIGTERM");
-					setTimeout(() => {
-						if (!settled) killProcessGroup(child, "SIGKILL");
-					}, EXEC_KILL_ESCALATION_GRACE_MS).unref?.();
-				};
-				const onChunk = (slot, chunk) => {
-					if (appendCapped(slot, chunk, maxBuffer) !== "ok" && !bufferTruncated) {
-						bufferTruncated = true;
-						killWithEscalation();
-					}
-				};
-				child.stdout?.on("data", (chunk) => onChunk(stdoutSlot, chunk));
-				child.stderr?.on("data", (chunk) => onChunk(stderrSlot, chunk));
-				const timeoutTimer = timeoutMs > 0 ? setTimeout(() => {
-					timedOut = true;
-					killWithEscalation();
-				}, timeoutMs) : void 0;
-				const onAbort = () => {
-					killedByAbort = true;
+			let bufferTruncated = false;
+			let timedOut = false;
+			let killedByAbort = false;
+			let settled = false;
+			const killWithEscalation = () => {
+				killProcessGroup(child, "SIGTERM");
+				setTimeout(() => {
+					if (!settled) killProcessGroup(child, "SIGKILL");
+				}, EXEC_KILL_ESCALATION_GRACE_MS).unref?.();
+			};
+			const onChunk = (slot, chunk) => {
+				if (appendCapped(slot, chunk, maxBuffer) !== "ok" && !bufferTruncated) {
+					bufferTruncated = true;
 					killWithEscalation();
+				}
+			};
+			child.stdout?.on("data", (chunk) => onChunk(stdoutSlot, chunk));
+			child.stderr?.on("data", (chunk) => onChunk(stderrSlot, chunk));
+			const timeoutTimer = timeoutMs > 0 ? setTimeout(() => {
+				timedOut = true;
+				killWithEscalation();
+			}, timeoutMs) : void 0;
+			const onAbort = () => {
+				killedByAbort = true;
+				killWithEscalation();
+			};
+			const userSignal = options?.signal;
+			if (userSignal) userSignal.addEventListener("abort", onAbort, { once: true });
+			let exitGraceTimer;
+			const settle = (exitCode, extraStderr) => {
+				if (settled) return;
+				settled = true;
+				if (timeoutTimer) clearTimeout(timeoutTimer);
+				if (exitGraceTimer) clearTimeout(exitGraceTimer);
+				if (userSignal) userSignal.removeEventListener("abort", onAbort);
+				const finalStderr = extraStderr ? stderrSlot.text ? `${stderrSlot.text}\n${extraStderr}` : extraStderr : stderrSlot.text;
+				const result = {
+					stdout: stdoutSlot.text,
+					stderr: finalStderr,
+					exitCode
 				};
-				const userSignal = options?.signal;
-				if (userSignal) userSignal.addEventListener("abort", onAbort, { once: true });
-				let exitGraceTimer;
-				const settle = (exitCode, extraStderr) => {
+				resolveP(isolation ? annotateDenial(result, isolation) : result);
+			};
+			const settleFromStatus = (code, signal) => {
+				if (killedByAbort) {
+					settle(143, "aborted by signal");
+					return;
+				}
+				if (timedOut) {
+					settle(124, `command timed out after ${timeoutMs}ms`);
+					return;
+				}
+				if (bufferTruncated) {
+					settle(143, outputExceededMessage(maxBuffer, "process killed"));
+					return;
+				}
+				if (signal) {
+					settle(143, `terminated by signal ${signal}`);
+					return;
+				}
+				settle(typeof code === "number" ? code : 1);
+			};
+			child.on("error", (err) => {
+				settle(1, err.message);
+			});
+			child.on("close", (code, signal) => settleFromStatus(code, signal));
+			child.on("exit", (code, signal) => {
+				exitGraceTimer = setTimeout(() => {
 					if (settled) return;
-					settled = true;
-					if (timeoutTimer) clearTimeout(timeoutTimer);
-					if (exitGraceTimer) clearTimeout(exitGraceTimer);
-					if (userSignal) userSignal.removeEventListener("abort", onAbort);
-					const finalStderr = extraStderr ? stderrSlot.text ? `${stderrSlot.text}\n${extraStderr}` : extraStderr : stderrSlot.text;
-					const result = {
-						stdout: stdoutSlot.text,
-						stderr: finalStderr,
-						exitCode
-					};
-					resolveP(isolation ? annotateDenial(result, isolation) : result);
-				};
-				const settleFromStatus = (code, signal) => {
-					if (killedByAbort) {
-						settle(143, "aborted by signal");
-						return;
-					}
-					if (timedOut) {
-						settle(124, `command timed out after ${timeoutMs}ms`);
-						return;
-					}
-					if (bufferTruncated) {
-						settle(143, outputExceededMessage(maxBuffer, "process killed"));
-						return;
-					}
-					if (signal) {
-						settle(143, `terminated by signal ${signal}`);
-						return;
-					}
-					settle(typeof code === "number" ? code : 1);
-				};
-				child.on("error", (err) => {
-					settle(1, err.message);
-				});
-				child.on("close", (code, signal) => settleFromStatus(code, signal));
-				child.on("exit", (code, signal) => {
-					exitGraceTimer = setTimeout(() => {
-						if (settled) return;
-						child.stdout?.destroy();
-						child.stderr?.destroy();
-						settleFromStatus(code, signal);
-					}, EXIT_PIPE_DRAIN_GRACE_MS);
-					exitGraceTimer.unref?.();
-				});
+					child.stdout?.destroy();
+					child.stderr?.destroy();
+					settleFromStatus(code, signal);
+				}, EXIT_PIPE_DRAIN_GRACE_MS);
+				exitGraceTimer.unref?.();
 			});
-		},
-		async readFile(handle, path) {
-			return readFile(await resolveContained(handle, path), "utf-8");
+		});
+	} };
+}
+//#endregion
+//#region src/contexts/git-ls-files.ts
+/**
+* Pure (node-free) `git ls-files` helpers shared by the gitignore-aware paths
+* of the `glob` and `grep` tools.
+*
+* `git ls-files --cached --others --exclude-standard` lists tracked files plus
+* untracked-but-not-ignored files, applying `.gitignore`, `.git/info/exclude`,
+* and the user's global excludes. Git never descends ignored directories
+* (`node_modules`, build output, …), so this is both correct and sub-second on
+* large repos — unlike a raw filesystem walk.
+*
+* This module has ZERO node imports so it can be pulled into edge/workerd
+* bundles (e.g. via the `grep` tool, which drives git through the execution
+* context's `exec` seam). The node-spawn variant lives in
+* `./git-ls-files-local`.
+*/
+/** Argv for `git ls-files`, NUL-delimited so paths with newlines stay intact. */
+const GIT_LS_FILES_ARGS = [
+	"ls-files",
+	"--cached",
+	"--others",
+	"--exclude-standard",
+	"-z"
+];
+/** The same invocation as a shell command string for the `exec` seam. */
+const GIT_LS_FILES_COMMAND = `git ${GIT_LS_FILES_ARGS.join(" ")}`;
+/** Split NUL-delimited `git ls-files -z` output into paths. */
+function parseGitLsFiles(stdout) {
+	return stdout.split("\0").filter((p) => p.length > 0);
+}
+//#endregion
+//#region src/contexts/git-ls-files-local.ts
+/**
+* Node-spawn `git ls-files` runner used by the local process context's glob.
+*
+* Kept separate from `./git-ls-files` (which stays node-free for edge bundles)
+* because this leg imports `node:child_process`.
+*/
+/**
+* Run `git ls-files` in `cwd` and return its non-ignored paths (relative to
+* `cwd`). Returns `null` when the directory is not a git repo, git is missing,
+* or the call aborts — callers treat `null` as "fall back to a filesystem
+* walk". Never throws.
+*/
+async function gitListFilesLocal(cwd, signal) {
+	return new Promise((resolveP) => {
+		let child;
+		try {
+			child = spawn("git", [...GIT_LS_FILES_ARGS], {
+				cwd,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch {
+			resolveP(null);
+			return;
+		}
+		if (signal?.aborted) {
+			child.kill("SIGTERM");
+			resolveP(null);
+			return;
+		}
+		const stdoutChunks = [];
+		const onAbort = () => child.kill("SIGTERM");
+		signal?.addEventListener("abort", onAbort, { once: true });
+		child.stdout?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+		child.on("error", () => {
+			signal?.removeEventListener("abort", onAbort);
+			resolveP(null);
+		});
+		child.on("close", (code) => {
+			signal?.removeEventListener("abort", onAbort);
+			if (code !== 0 || signal?.aborted) {
+				resolveP(null);
+				return;
+			}
+			resolveP(parseGitLsFiles(stdoutChunks.join("")));
+		});
+	});
+}
+//#endregion
+//#region src/contexts/glob.ts
+const loadNativeNodeGlob = lazyAsync(async () => {
+	const candidate = (await import("node:fs/promises")).glob;
+	return typeof candidate === "function" ? candidate : void 0;
+});
+function forcePortable() {
+	return globalThis.__zidaneForcePortableGlobForTests === true;
+}
+async function loadNodeGlob() {
+	if (forcePortable()) return void 0;
+	return loadNativeNodeGlob();
+}
+/**
+* Bun's `node:fs/promises.glob` buffers the entire directory walk before
+* yielding (so an early `limit` break never fires — a broad `**` pattern over
+* a large `node_modules` hangs). `Bun.Glob().scan()` streams incrementally and
+* is the fast path under Bun. Returns undefined off Bun or when tests force the
+* portable walker.
+*/
+function loadBunGlob() {
+	if (forcePortable()) return void 0;
+	const bun = globalThis.Bun;
+	return bun && typeof bun.Glob === "function" ? bun.Glob : void 0;
+}
+function escapeRegexChar(char) {
+	return /[\\^$.*+?()[\]{}|]/.test(char) ? `\\${char}` : char;
+}
+function expandBraces(pattern) {
+	const start = pattern.indexOf("{");
+	if (start === -1) return [pattern];
+	const end = pattern.indexOf("}", start + 1);
+	if (end === -1) return [pattern];
+	const body = pattern.slice(start + 1, end);
+	if (!body || !body.includes(",")) return [pattern];
+	return body.split(",").flatMap((part) => expandBraces(`${pattern.slice(0, start)}${part}${pattern.slice(end + 1)}`));
+}
+function globPatternToRegex(pattern) {
+	let out = "^";
+	for (let i = 0; i < pattern.length; i++) {
+		const char = pattern[i];
+		const next = pattern[i + 1];
+		if (char === "*") {
+			if (next === "*") {
+				if (pattern[i + 2] === "/") {
+					out += "(?:[^/]+/)*";
+					i += 2;
+				} else {
+					out += ".*";
+					i += 1;
+				}
+			} else out += "[^/]*";
+		} else if (char === "?") out += "[^/]";
+		else if (char === "[") {
+			const end = pattern.indexOf("]", i + 1);
+			if (end === -1) out += "\\[";
+			else {
+				let cls = pattern.slice(i + 1, end);
+				if (cls.startsWith("!")) cls = `^${cls.slice(1)}`;
+				out += `[${cls}]`;
+				i = end;
+			}
+		} else out += escapeRegexChar(char);
+	}
+	return new RegExp(`${out}$`);
+}
+function globLiteralPrefix(pattern) {
+	const firstMeta = pattern.search(/[*?[\]{}]/);
+	const prefix = firstMeta === -1 ? dirname(pattern) : pattern.slice(0, firstMeta);
+	const slash = prefix.lastIndexOf("/");
+	if (slash === -1) return "";
+	return prefix.slice(0, slash);
+}
+/**
+* True when a pattern can match files outside `cwd` — an absolute path, a
+* Windows drive, or any `..` segment. Such patterns can't use the `git
+* ls-files` path (git only knows files under the repo) and fall back to the
+* filesystem walk.
+*/
+function patternEscapesCwd(pattern) {
+	const norm = pattern.split(sep).join("/");
+	if (norm.startsWith("/") || /^[a-z]:/i.test(norm)) return true;
+	return norm.split("/").includes("..");
+}
+async function addMetadata(cwd, rel, includeMetadata) {
+	try {
+		const s = await stat(resolve(cwd, rel));
+		if (!s.isFile()) return null;
+		return includeMetadata ? {
+			path: rel,
+			size: s.size,
+			mtimeMs: s.mtimeMs
+		} : { path: rel };
+	} catch {
+		return null;
+	}
+}
+function compilePattern(pattern) {
+	return expandBraces(pattern.split(sep).join("/")).map(globPatternToRegex);
+}
+/** Match the (already non-ignored) `git ls-files` set against the glob pattern. */
+async function matchGitFiles(gitFiles, pattern, cwd, limit, includeMetadata, signal) {
+	const regexes = compilePattern(pattern);
+	const out = [];
+	for (const rel of gitFiles) {
+		if (signal?.aborted || out.length >= limit) break;
+		if (!regexes.some((regex) => regex.test(rel))) continue;
+		out.push(includeMetadata ? await addMetadata(cwd, rel, true) ?? { path: rel } : { path: rel });
+	}
+	return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+/** Depth-first walk that matches against `regexes` and stops at `limit`. */
+async function walkMatch(root, prefix, regexes, cwd, limit, includeMetadata, signal, out) {
+	if (out.length >= limit || signal?.aborted) return;
+	let entries;
+	try {
+		entries = await readdir(resolve(root, prefix), {
+			encoding: "utf8",
+			withFileTypes: true
+		});
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (out.length >= limit || signal?.aborted) return;
+		const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+		if (entry.isDirectory()) await walkMatch(root, rel, regexes, cwd, limit, includeMetadata, signal, out);
+		else if (entry.isFile() && regexes.some((regex) => regex.test(rel))) out.push(includeMetadata ? await addMetadata(cwd, rel, true) ?? { path: rel } : { path: rel });
+	}
+}
+async function globPortable(pattern, cwd, limit, includeMetadata, signal) {
+	const normalized = pattern.split(sep).join("/");
+	const startPrefix = globLiteralPrefix(normalized);
+	const regexes = expandBraces(normalized).map(globPatternToRegex);
+	const out = [];
+	await walkMatch(cwd, startPrefix, regexes, cwd, limit, includeMetadata, signal, out);
+	return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+async function collectFromIterable(iter, cwd, limit, includeMetadata, signal) {
+	const results = [];
+	try {
+		for await (const rel of iter) {
+			if (signal?.aborted) break;
+			const entry = await addMetadata(cwd, rel, includeMetadata);
+			if (!entry) continue;
+			results.push(entry);
+			if (results.length >= limit) break;
+		}
+	} catch {
+		return null;
+	}
+	return results.sort((a, b) => a.path.localeCompare(b.path));
+}
+function globViaBun(BunGlob, pattern, cwd, limit, includeMetadata, signal) {
+	return collectFromIterable(new BunGlob(pattern).scan({
+		cwd,
+		onlyFiles: true,
+		dot: true
+	}), cwd, limit, includeMetadata, signal);
+}
+async function globFilesLocal(pattern, cwd, options) {
+	const includeMetadata = options.metadata === true;
+	const { limit, signal } = options;
+	if (options.gitignore !== false && !forcePortable() && !patternEscapesCwd(pattern)) {
+		const gitFiles = await gitListFilesLocal(cwd, signal);
+		if (gitFiles) return matchGitFiles(gitFiles, pattern, cwd, limit, includeMetadata, signal);
+	}
+	const bunGlob = loadBunGlob();
+	if (bunGlob) {
+		const viaBun = await globViaBun(bunGlob, pattern, cwd, limit, includeMetadata, signal);
+		if (viaBun) return viaBun;
+	} else {
+		const nodeGlob = await loadNodeGlob();
+		if (nodeGlob) {
+			const viaNode = await collectFromIterable(nodeGlob(pattern, { cwd }), cwd, limit, includeMetadata, signal);
+			if (viaNode) return viaNode;
+		}
+	}
+	return globPortable(pattern, cwd, limit, includeMetadata, signal);
+}
+//#endregion
+//#region src/contexts/process-files.ts
+function processFileMethods(s) {
+	const { workspaceRoot, isolation } = s;
+	/**
+	* Resolve `path` against the handle cwd and, when a `workspaceRoot` is
+	* configured, reject anything that escapes it. Uses `realpath` on the
+	* nearest existing ancestor so symlink escapes (and `..`) are caught for
+	* both existing and not-yet-created targets.
+	*/
+	async function resolveContained(handle, path) {
+		const full = resolve(handle.cwd, path);
+		if (workspaceRoot === void 0) return full;
+		const canonical = await canonicalizeForCheck(full);
+		const canonicalRoot = await realpath(workspaceRoot).catch(() => workspaceRoot);
+		if (!isWithinRoot(canonicalRoot, canonical)) throw new Error(`Path escapes the workspace root: ${path} (resolved outside ${canonicalRoot})`);
+		return full;
+	}
+	/**
+	* Canonicalize the deepest existing ancestor of `full` to defeat symlink
+	* escapes; the non-existent tail (for writes) is appended back verbatim.
+	*/
+	async function canonicalizeForCheck(full) {
+		let existing = full;
+		const tail = [];
+		while (true) try {
+			existing = await realpath(existing);
+			break;
+		} catch {
+			const parent = dirname(existing);
+			if (parent === existing) {
+				existing = parent;
+				break;
+			}
+			tail.unshift(relative(parent, existing));
+			existing = parent;
+		}
+		return tail.length ? resolve(existing, ...tail) : existing;
+	}
+	/**
+	* In-process counterpart of the sandbox's write policy: `writeFile` (and
+	* so the `write_file` / `edit` tools) may only target `isolation.writableRoots`.
+	* Reads are deliberately unrestricted — same boundary the kernel enforces
+	* for shell commands, so the two never disagree about where writes land.
+	*/
+	async function assertWritable(full, path) {
+		if (!isolation) return;
+		const canonical = await canonicalizeForCheck(full);
+		if (!isolation.writableRoots.some((root) => isWithinRoot(root, canonical))) throw new Error(`[sandbox] write denied: ${path} is outside the writable roots (${isolation.writableRoots.join(", ")}). Ask the user to add it under Settings → "Sandbox writable paths" or turn off "Sandbox shell commands".`);
+	}
+	return {
+		async readFile(handle, path) {
+			return readFile(await resolveContained(handle, path), "utf-8");
 		},
 		async fileSize(handle, path) {
 			try {
@@ -913,67 +1396,252 @@ function createProcessContext(config) {
 				return contained;
 			}
 			return (await readdir(await resolveContained(handle, path), { withFileTypes: true })).map((d) => d.isDirectory() ? `${d.name}/` : d.name);
+		}
+	};
+}
+//#endregion
+//#region src/contexts/ansi-strip.ts
+/** Parser states: plain text, after ESC, in a CSI, in an OSC/DCS string, after ESC inside one. */
+const State = {
+	Text: 0,
+	Esc: 1,
+	Csi: 2,
+	Str: 3,
+	StrEsc: 4
+};
+function createAnsiStripper(options = {}) {
+	let state = State.Text;
+	/** Body of the OSC / DCS / APC string being read; OSC only is kept. */
+	let str = "";
+	let strIsOsc = false;
+	let line = "";
+	/** A `\r` arrived; the next printable rewinds the line unless `\n` follows. */
+	let pendingCr = false;
+	/** Part of the current line was handed out by `takePartial`: a rewind must start a new line. */
+	let taken = false;
+	const endString = () => {
+		if (strIsOsc && options.onTitle) {
+			const semi = str.indexOf(";");
+			const code = semi === -1 ? str : str.slice(0, semi);
+			if ((code === "0" || code === "2") && semi !== -1) options.onTitle(str.slice(semi + 1));
+		}
+		str = "";
+		state = State.Text;
+	};
+	return {
+		push(chunk) {
+			let out = "";
+			for (let i = 0; i < chunk.length; i++) {
+				const ch = chunk[i];
+				const code = ch.charCodeAt(0);
+				switch (state) {
+					case State.Text:
+						if (code === 27) state = State.Esc;
+						else if (ch === "\n") {
+							out += `${line}\n`;
+							line = "";
+							pendingCr = false;
+							taken = false;
+						} else if (ch === "\r") pendingCr = true;
+						else if (code === 8) line = line.slice(0, -1);
+						else if (code === 155) state = State.Csi;
+						else if (code === 157) {
+							state = State.Str;
+							strIsOsc = true;
+						} else if (ch === "	" || code >= 32) {
+							if (code >= 127 && code < 160) break;
+							if (pendingCr) {
+								if (taken) out += "\n";
+								taken = false;
+								line = "";
+								pendingCr = false;
+							}
+							line += ch;
+						}
+						break;
+					case State.Esc:
+						if (ch === "[") state = State.Csi;
+						else if (ch === "]" || ch === "P" || ch === "X" || ch === "^" || ch === "_") {
+							state = State.Str;
+							strIsOsc = ch === "]";
+							str = "";
+						} else if (code >= 32 && code <= 47) {} else state = State.Text;
+						break;
+					case State.Csi:
+						if (code >= 64 && code <= 126) state = State.Text;
+						break;
+					case State.Str:
+						if (code === 7) endString();
+						else if (code === 27) state = State.StrEsc;
+						else if (code === 156) endString();
+						else if (str.length < 4096) str += ch;
+						break;
+					case State.StrEsc: if (ch === "\\") endString();
+					else {
+						str += `\x1B${ch}`;
+						state = State.Str;
+					}
+				}
+			}
+			return out;
 		},
-		/**
-		* Live bidirectional stream to a child process — see
-		* `ExecutionContext.execStream` for the seam contract.
-		*
-		* The reference implementation: an ordinary piped `spawn`, so both
-		* streams stay separate and no terminal line discipline sits between
-		* the caller and the child. Sandbox-backed contexts have to work
-		* harder to reach the same shape.
-		*
-		* Unlike `execBackground`, nothing here lands in the `tasks` registry:
-		* this handle is owned by its caller (an MCP transport's `close()`),
-		* not by the model-facing background-task list that `shell_kill` /
-		* `wait_task` walk. It IS tracked in `streamChildren` so the shared
-		* orphan reaper and `destroy()` can sweep it — detached process-group
-		* semantics (needed so `kill()` takes the child's own children with
-		* it) are exactly what would otherwise leak a live server per crash.
-		*/
-		async execStream(handle, command, options) {
-			const cwd = options?.cwd ? resolve(handle.cwd, options.cwd) : handle.cwd;
-			const spawnChild = await loadSpawn();
-			options?.signal?.throwIfAborted();
-			const blocked = isolationBlocker();
-			if (blocked) throw new Error(blocked.stderr);
-			const shell = shellCommand(command);
-			const child = spawnChild(shell.file, shell.args, {
-				cwd,
-				env: {
-					...baseEnv,
-					...defaultEnv,
-					...options?.env
-				},
-				stdio: [
-					"pipe",
-					"pipe",
-					"pipe"
-				],
-				detached: SUPPORTS_PROCESS_GROUPS
-			});
-			registerExitHandler();
-			streamChildren.set(child, handle.id);
-			let spawnError = null;
-			child.on("error", (err) => {
-				spawnError = err;
-			});
-			const exited = new Promise((resolveExit) => {
-				child.once("close", (code, signalName) => {
-					streamChildren.delete(child);
-					resolveExit(code !== null ? code : signalName === "SIGTERM" ? 143 : signalName ? 128 : 1);
-				});
+		partial: () => line,
+		takePartial() {
+			const text = line;
+			if (text) taken = true;
+			line = "";
+			return text;
+		}
+	};
+}
+//#endregion
+//#region src/contexts/process-shell.ts
+function createProcessShell(s) {
+	const { baseEnv, defaultEnv, isolation, isolationState } = s;
+	/**
+	* `{ file, args }` for `/bin/sh -c command`, wrapped in the sandbox when
+	* isolation is on. Callers check `isolationState.ok` first (the three
+	* shell entry points return `unavailableResult` / throw before spawning).
+	*/
+	function shellCommand(command) {
+		if (isolation && isolationState?.ok) return wrapCommand(isolationState.backend, isolationState.executable, isolation, command);
+		return {
+			file: "/bin/sh",
+			args: ["-c", command]
+		};
+	}
+	/** Failure result when isolation was requested but cannot be enforced; `undefined` = proceed. */
+	function isolationBlocker() {
+		return isolationState && !isolationState.ok ? unavailableResult(isolationState.reason) : void 0;
+	}
+	/**
+	* A background task in a PTY, as a `ChildProcess` look-alike whose stdout
+	* carries the log text. A line still unfinished after a quiet moment (a
+	* prompt waiting for input) is written out too, so the log shows it.
+	*/
+	function spawnTerminalTask(argv, cwd, extraEnv, tty) {
+		const stripper = createAnsiStripper();
+		const decoder = new TextDecoder();
+		let quiet;
+		let emitLog = () => {};
+		const flushPartial = () => {
+			const rest = stripper.takePartial();
+			if (rest) emitLog(rest);
+		};
+		const pty = spawnLocalPty(argv, {
+			cwd,
+			env: terminalEnv(extraEnv),
+			cols: tty.cols,
+			rows: tty.rows,
+			onData: (data) => {
+				tty.onData(data);
+				const text = stripper.push(decoder.decode(data, { stream: true }));
+				if (text) emitLog(text);
+				if (quiet) clearTimeout(quiet);
+				quiet = setTimeout(flushPartial, 300);
+				quiet.unref?.();
+			}
+		});
+		const { child, stdout } = ptyChildProcess(pty);
+		const encoder = new TextEncoder();
+		emitLog = (text) => stdout.emit("data", encoder.encode(text));
+		pty.exited.then(() => {
+			if (quiet) clearTimeout(quiet);
+			flushPartial();
+		});
+		tty.onReady?.({
+			write: pty.write,
+			resize: pty.resize
+		});
+		return child;
+	}
+	/** The environment of a terminal: what commands get, plus terminal identity, minus `unset`. */
+	function terminalEnv(extra, unset = []) {
+		const env = {};
+		for (const [key, value] of Object.entries({
+			...baseEnv,
+			...defaultEnv,
+			...extra,
+			...TERMINAL_ENV
+		})) if (typeof value === "string" && !unset.includes(key)) env[key] = value;
+		return env;
+	}
+	return {
+		shellCommand,
+		isolationBlocker,
+		spawnTerminalTask,
+		terminalEnv
+	};
+}
+//#endregion
+//#region src/contexts/process-stream.ts
+function processStreamMethods(s, sh) {
+	const { baseEnv, defaultEnv, registerExitHandler, streamChildren } = s;
+	const { shellCommand, isolationBlocker } = sh;
+	return { 
+	/**
+	* Live bidirectional stream to a child process — see
+	* `ExecutionContext.execStream` for the seam contract.
+	*
+	* The reference implementation: an ordinary piped `spawn`, so both
+	* streams stay separate and no terminal line discipline sits between
+	* the caller and the child. Sandbox-backed contexts have to work
+	* harder to reach the same shape.
+	*
+	* Unlike `execBackground`, nothing here lands in the `tasks` registry:
+	* this handle is owned by its caller (an MCP transport's `close()`),
+	* not by the model-facing background-task list that `shell_kill` /
+	* `wait_task` walk. It IS tracked in `streamChildren` so the shared
+	* orphan reaper and `destroy()` can sweep it — detached process-group
+	* semantics (needed so `kill()` takes the child's own children with
+	* it) are exactly what would otherwise leak a live server per crash.
+	*/
+async execStream(handle, command, options) {
+		const cwd = options?.cwd ? resolve(handle.cwd, options.cwd) : handle.cwd;
+		const spawnChild = await loadSpawn();
+		options?.signal?.throwIfAborted();
+		const blocked = isolationBlocker();
+		if (blocked) throw new Error(blocked.stderr);
+		const shell = shellCommand(command);
+		const child = spawnChild(shell.file, shell.args, {
+			cwd,
+			env: {
+				...baseEnv,
+				...defaultEnv,
+				...options?.env
+			},
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			detached: SUPPORTS_PROCESS_GROUPS
+		});
+		registerExitHandler();
+		streamChildren.set(child, handle.id);
+		let spawnError = null;
+		child.on("error", (err) => {
+			spawnError = err;
+		});
+		let closed = false;
+		let escalation;
+		const exited = new Promise((resolveExit) => {
+			child.once("close", (code, signalName) => {
+				closed = true;
+				clearTimeout(escalation);
+				streamChildren.delete(child);
+				resolveExit(code !== null ? code : signalName === "SIGTERM" ? 143 : signalName ? 128 : 1);
 			});
-			const kill = async () => {
-				if (child.exitCode !== null || child.signalCode !== null) return;
-				const pid = child.pid;
-				if (pid === void 0) return;
-				try {
-					if (SUPPORTS_PROCESS_GROUPS) process.kill(-pid, "SIGTERM");
-					else process.kill(pid, "SIGTERM");
-				} catch {}
-			};
-			if (options?.signal) if (options.signal.aborted) kill();
+		});
+		const kill = async () => {
+			if (closed || child.pid === void 0) return;
+			killProcessGroup(child, "SIGTERM");
+			if (escalation) return;
+			escalation = setTimeout(killProcessGroup, EXEC_KILL_ESCALATION_GRACE_MS, child, "SIGKILL");
+			escalation.unref?.();
+		};
+		if (options?.signal) {
+			if (options.signal.aborted) kill();
 			else {
 				const onAbort = () => {
 					kill();
@@ -982,168 +1650,29 @@ function createProcessContext(config) {
 				options.signal.addEventListener("abort", onAbort, { once: true });
 				exited.then(detach, detach);
 			}
-			return {
-				pid: child.pid ?? -1,
-				stdout: child.stdout,
-				stderr: child.stderr,
-				write: async (data) => {
-					if (spawnError) throw spawnError;
-					const stdin = child.stdin;
-					if (!stdin || stdin.destroyed) throw new Error(`execStream: stdin is closed (pid ${child.pid ?? -1})`);
-					await new Promise((resolveWrite, rejectWrite) => {
-						stdin.write(data, (err) => err ? rejectWrite(err) : resolveWrite());
-					});
-				},
-				kill,
-				exited
-			};
-		},
-		async execBackground(handle, command, options) {
-			const cwd = options.cwd ? resolve(handle.cwd, options.cwd) : handle.cwd;
-			const spawnChild = await loadSpawn();
-			const blocked = isolationBlocker();
-			if (blocked) throw new Error(blocked.stderr);
-			await mkdir(options.outputDir, { recursive: true });
-			const taskId = `bash_${++taskCounter}`;
-			assertSafeTaskId(taskId);
-			const outputPath = resolve(options.outputDir, `${taskId}.${contextTimestamp}.log`);
-			registerExitHandler();
-			const outputStream = createWriteStream(outputPath, { flags: "a" });
-			outputStream.on("error", (err) => {
-				if (process.env.ZIDANE_DEBUG) process.stderr.write(`[zidane/contexts] task ${taskId} log stream error: ${err.message}\n`);
-			});
-			const shell = shellCommand(command);
-			const child = spawnChild(shell.file, shell.args, {
-				cwd,
-				env: {
-					...baseEnv,
-					...defaultEnv,
-					...options.env
-				},
-				stdio: [
-					"ignore",
-					"pipe",
-					"pipe"
-				],
-				detached: SUPPORTS_PROCESS_GROUPS
-			});
-			const state = {
-				taskId,
-				handleId: handle.id,
-				pid: child.pid ?? -1,
-				command,
-				cwd,
-				startedAt: Date.now(),
-				outputPath,
-				outputStream,
-				child,
-				status: "running",
-				bytesWritten: 0,
-				settled: false,
-				onExit: options.onExit
-			};
-			tasks.set(taskId, state);
-			const maxOutputBytes = typeof options.maxOutputBytes === "number" && options.maxOutputBytes > 0 ? options.maxOutputBytes : void 0;
-			let droppedBytes = 0;
-			let capExhausted = false;
-			const stallTimeoutMs = typeof options.stallTimeoutMs === "number" && options.stallTimeoutMs > 0 ? options.stallTimeoutMs : void 0;
-			const onStall = options.onStall;
-			let stallTimer;
-			let lastOutputAt = Date.now();
-			const armStallTimer = () => {
-				if (!stallTimeoutMs || !onStall) return;
-				if (stallTimer) clearTimeout(stallTimer);
-				stallTimer = setTimeout(() => {
-					stallTimer = void 0;
-					if (state.settled) return;
-					try {
-						onStall({
-							taskId,
-							command,
-							outputPath,
-							stalledForMs: Date.now() - lastOutputAt,
-							bytesWritten: state.bytesWritten
-						});
-					} catch (err) {
-						if (process.env.ZIDANE_DEBUG) process.stderr.write(`[zidane/contexts] task ${taskId} onStall threw: ${err instanceof Error ? err.message : String(err)}\n`);
-					}
-				}, stallTimeoutMs);
-				stallTimer.unref?.();
-			};
-			const clearStallTimer = () => {
-				if (stallTimer) {
-					clearTimeout(stallTimer);
-					stallTimer = void 0;
-				}
-			};
-			armStallTimer();
-			const appendChunk = (chunk) => {
-				state.bytesWritten += chunk.length;
-				lastOutputAt = Date.now();
-				armStallTimer();
-				if (maxOutputBytes !== void 0) {
-					const onDisk = state.bytesWritten - droppedBytes - chunk.length;
-					if (capExhausted || onDisk >= maxOutputBytes) {
-						capExhausted = true;
-						droppedBytes += chunk.length;
-						return;
-					}
-					const room = maxOutputBytes - onDisk;
-					if (chunk.length > room) {
-						capExhausted = true;
-						let end = room;
-						while (end > 0 && (chunk[end] & 192) === 128) end--;
-						droppedBytes += chunk.length - end;
-						if (end > 0) outputStream.write(chunk.subarray(0, end));
-						return;
-					}
-				}
-				outputStream.write(chunk);
-			};
-			child.stdout?.on("data", (chunk) => appendChunk(chunk));
-			child.stderr?.on("data", (chunk) => appendChunk(chunk));
-			const settle = (cause, code, signal, errMessage) => {
-				if (state.settled) return;
-				state.settled = true;
-				clearStallTimer();
-				state.endedAt = Date.now();
-				const status = signal === "SIGTERM" || state.killRequested ? "killed" : "exited";
-				const exitCode = code !== null ? code : signal === "SIGTERM" ? 143 : signal ? 128 : 1;
-				state.status = status;
-				state.exitCode = exitCode;
-				if (signal) state.signal = signal;
-				if (errMessage) try {
-					outputStream.write(`\n${errMessage}\n`);
-				} catch {}
-				if (droppedBytes > 0) try {
-					outputStream.write(`\n<output-truncated bytes-dropped="${droppedBytes}"/>\n`);
-				} catch {}
-				outputStream.end(() => {
-					try {
-						state.onExit?.(stateToTaskExitInfo(state));
-					} catch (err) {
-						if (process.env.ZIDANE_DEBUG) process.stderr.write(`[zidane/contexts] task ${taskId} onExit threw: ${err instanceof Error ? err.message : String(err)}\n`);
-					}
+		}
+		return {
+			pid: child.pid ?? -1,
+			stdout: child.stdout,
+			stderr: child.stderr,
+			write: async (data) => {
+				if (spawnError) throw spawnError;
+				const stdin = child.stdin;
+				if (!stdin || stdin.destroyed) throw new Error(`execStream: stdin is closed (pid ${child.pid ?? -1})`);
+				await new Promise((resolveWrite, rejectWrite) => {
+					stdin.write(data, (err) => err ? rejectWrite(err) : resolveWrite());
 				});
-				state.child = void 0;
-				state.outputStream = void 0;
-			};
-			child.on("close", (code, signal) => settle("close", code, signal));
-			child.on("error", (err) => settle("error", null, null, `[spawn error] ${err.message}`));
-			child.on("exit", (code, signal) => {
-				setTimeout(() => {
-					if (state.settled) return;
-					child.stdout?.destroy();
-					child.stderr?.destroy();
-					settle("close", code, signal);
-				}, EXIT_PIPE_DRAIN_GRACE_MS).unref?.();
-			});
-			return {
-				taskId,
-				pid: state.pid,
-				outputPath
-			};
-		},
+			},
+			kill,
+			exited
+		};
+	} };
+}
+//#endregion
+//#region src/contexts/process-tasks.ts
+function processTaskMethods(s) {
+	const { tasks, destroyGraceMs, streamChildren, handles } = s;
+	return {
 		async killBackground(handle, taskId) {
 			const state = tasks.get(taskId);
 			if (!state || state.handleId !== handle.id) return null;
@@ -1154,11 +1683,7 @@ function createProcessContext(config) {
 					resolveP();
 					return;
 				}
-				const originalOnExit = state.onExit;
-				state.onExit = (info) => {
-					originalOnExit?.(info);
-					resolveP();
-				};
+				state.exitWatchers.push(() => resolveP());
 			});
 			killProcessGroup(state.child, "SIGTERM");
 			await closed;
@@ -1177,16 +1702,18 @@ function createProcessContext(config) {
 					done = true;
 					if (timer) clearTimeout(timer);
 					signal?.removeEventListener("abort", onAbort);
+					const index = state.exitWatchers.indexOf(watcher);
+					if (index >= 0) state.exitWatchers.splice(index, 1);
 					resolveP(value);
 				};
 				function onAbort() {
 					finish(null);
 				}
-				const originalOnExit = state.onExit;
-				state.onExit = (info) => {
-					originalOnExit?.(info);
-					finish(stateToTaskExitInfo(state));
-				};
+				const task = state;
+				function watcher() {
+					finish(stateToTaskExitInfo(task));
+				}
+				state.exitWatchers.push(watcher);
 				if (signal) {
 					if (signal.aborted) {
 						finish(null);
@@ -1201,13 +1728,13 @@ function createProcessContext(config) {
 				}
 			});
 		},
-		async reassignBackgroundTasks(fromHandle, toHandle, newOnExit) {
-			if (fromHandle.id === toHandle.id) return [];
+		async reassignBackgroundTasks(fromHandle, toHandle, newOnExit, newOnStall) {
 			const promoted = [];
 			for (const state of tasks.values()) {
 				if (state.handleId !== fromHandle.id || state.status !== "running") continue;
 				state.handleId = toHandle.id;
 				if (newOnExit) state.onExit = newOnExit;
+				if (newOnStall) state.onStall = newOnStall;
 				promoted.push(stateToTaskEntry(state));
 			}
 			return promoted;
@@ -1221,12 +1748,10 @@ function createProcessContext(config) {
 				state.killRequested = true;
 				await new Promise((resolveP) => {
 					let graceTimer;
-					const originalOnExit = state.onExit;
-					state.onExit = (info) => {
-						originalOnExit?.(info);
+					state.exitWatchers.push(() => {
 						if (graceTimer) clearTimeout(graceTimer);
 						resolveP();
-					};
+					});
 					killProcessGroup(state.child, "SIGTERM");
 					graceTimer = setTimeout(() => {
 						killProcessGroup(state.child, "SIGKILL");
@@ -1242,76 +1767,86 @@ function createProcessContext(config) {
 				streamChildren.delete(child);
 			}
 			handles.delete(handle.id);
-			if (exitHandlerRegistered && handles.size === 0) {
-				process.off("exit", exitHandler);
-				exitHandlerRegistered = false;
+			if (s.exitHandlerRegistered && handles.size === 0) {
+				process.off("exit", s.exitHandler);
+				s.exitHandlerRegistered = false;
 			}
 		}
 	};
 }
-/**
-* Send `signal` to the child's whole process group. Falls back to a
-* single-process kill on Windows (no POSIX process groups). Shared
-* across the foreground `exec` path, the background spawn / kill
-* paths, and the shutdown-time orphan reaper — keeping one definition
-* so the kill semantics can't drift between them.
-*/
-function killProcessGroup(child, signal) {
-	const pid = child?.pid;
-	if (pid === void 0) return;
-	try {
-		if (SUPPORTS_PROCESS_GROUPS) process.kill(-pid, signal);
-		else process.kill(pid, signal);
-	} catch {}
-}
-/**
-* Project a `TaskState` to the `TaskEntry` shape `listBackground` and
-* `reassignBackgroundTasks` return. Single helper keeps the shape
-* consistent across both call sites (and a future addition of fields
-* to `TaskEntry` only needs to land here).
-*/
-function stateToTaskEntry(state) {
-	return {
-		taskId: state.taskId,
-		pid: state.pid,
-		command: state.command,
-		cwd: state.cwd,
-		startedAt: state.startedAt,
-		...state.endedAt !== void 0 ? { endedAt: state.endedAt } : {},
-		outputPath: state.outputPath,
-		status: state.status,
-		...state.exitCode !== void 0 ? { exitCode: state.exitCode } : {},
-		...state.signal ? { signal: state.signal } : {},
-		bytesWritten: state.bytesWritten
-	};
-}
-/**
-* Project a settled `TaskState` to the `TaskExitInfo` shape `settle()`
-* fires from `onExit` and `killBackground` returns on the
-* cached-exit path. Pre-condition: `state.status !== 'running'`
-* (callers gate on this).
-*/
-function stateToTaskExitInfo(state) {
+//#endregion
+//#region src/contexts/process.ts
+function createProcessContext(config) {
+	const s = createProcessState(config);
+	const { handles, defaultCwd, isolation, isolationState } = s;
+	const sh = createProcessShell(s);
+	const { shellCommand, isolationBlocker, terminalEnv } = sh;
+	const files = processFileMethods(s);
+	const execM = processExecMethods(s, sh);
+	const streamM = processStreamMethods(s, sh);
+	const bg = processBackgroundMethods(s, sh);
+	const taskM = processTaskMethods(s);
 	return {
-		taskId: state.taskId,
-		status: state.status,
-		exitCode: state.exitCode ?? 0,
-		...state.signal ? { signal: state.signal } : {},
-		outputPath: state.outputPath,
-		durationMs: (state.endedAt ?? Date.now()) - state.startedAt,
-		command: state.command
+		type: "process",
+		capabilities: {
+			shell: true,
+			filesystem: true,
+			glob: true,
+			network: true,
+			gpu: false,
+			stream: true,
+			isolated: isolation !== void 0 && isolationState?.ok === true,
+			detachedTasks: "process-lifetime"
+		},
+		async spawn(overrides) {
+			const id = `process-${++s.counter}`;
+			const cwd = overrides?.cwd ?? defaultCwd;
+			let needsCreate = false;
+			try {
+				await stat(cwd);
+			} catch (err) {
+				needsCreate = err?.code === "ENOENT";
+			}
+			if (needsCreate) await mkdir(cwd, { recursive: true });
+			const handle = {
+				id,
+				type: "process",
+				cwd
+			};
+			handles.set(id, handle);
+			return handle;
+		},
+		exec: execM.exec,
+		readFile: files.readFile,
+		fileSize: files.fileSize,
+		readFileBinary: files.readFileBinary,
+		writeFile: files.writeFile,
+		listFiles: files.listFiles,
+		execStream: streamM.execStream,
+		...hasLocalPty() ? { async openTerminal(handle, options) {
+			const blocked = isolationBlocker();
+			if (blocked) throw new Error(blocked.stderr);
+			const env = terminalEnv(options.env, options.unsetEnv);
+			const shell = loginShell(env);
+			const argv = isolation && isolationState?.ok ? (({ file, args }) => [file, ...args])(shellCommand(`exec ${JSON.stringify(shell)} -l`)) : [shell, "-l"];
+			const pty = spawnLocalPty(argv, {
+				cwd: options.cwd ? resolve(handle.cwd, options.cwd) : handle.cwd,
+				env,
+				cols: options.cols,
+				rows: options.rows,
+				onData: options.onData
+			});
+			return localTerminalProcess(pty, { id: `pty-${pty.pid}` });
+		} } : {},
+		execBackground: bg.execBackground,
+		killBackground: taskM.killBackground,
+		waitBackground: taskM.waitBackground,
+		reassignBackgroundTasks: taskM.reassignBackgroundTasks,
+		listBackground: taskM.listBackground,
+		destroy: taskM.destroy
 	};
 }
 //#endregion
-//#region src/contexts/types.ts
-/**
-* Effective {@link DetachedTasksCapability} of a context, with the
-* backward-compatible inference for contexts that predate the field.
-*/
-function resolveDetachedTasksCapability(context) {
-	return context.capabilities.detachedTasks ?? (context.execBackground ? "process-lifetime" : "none");
-}
-//#endregion
-export { DEFAULT_UNREADABLE_DIRS as a, resolveUnreadableDirs as c, killProcessGroup as i, resolveWritableRoots as l, SUPPORTS_PROCESS_GROUPS as n, isolationAvailability as o, createProcessContext as r, parseAllowWriteSetting as s, resolveDetachedTasksCapability as t, resolveWritableRootsAsync as u };
+export { SUPPORTS_PROCESS_GROUPS as a, isolationAvailability as c, resolveWritableRoots as d, resolveWritableRootsAsync as f, parseGitLsFiles as i, parseAllowWriteSetting as l, createAnsiStripper as n, killProcessGroup as o, resolveDetachedTasksCapability as p, GIT_LS_FILES_COMMAND as r, DEFAULT_UNREADABLE_DIRS as s, createProcessContext as t, resolveUnreadableDirs as u };
 
-//# sourceMappingURL=contexts-CRE9pw07.js.map
+//# sourceMappingURL=contexts-d7UolYot.js.map