@oh-my-pi/pi-coding-agent 17.0.9 → 17.1.0

package/src/tools/bash.ts

@@ -10,13 +10,17 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import { ImageProtocol, TERMINAL } from "@oh-my-pi/pi-tui";
 import { getProjectDir, isEnoent, logger, prompt } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
-import { type BashResult, executeBash } from "../exec/bash-executor";
+import { applyDirenvPreflight, type BashResult, executeBash } from "../exec/bash-executor";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { InternalUrlRouter } from "../internal-urls";
 import { truncateToVisualLines } from "../modes/components/visual-truncate";
 import { highlightCode, type Theme } from "../modes/theme/theme";
 import bashDescription from "../prompts/tools/bash.md" with { type: "text" };
-import type { ClientBridgeTerminalExitStatus, ClientBridgeTerminalOutput } from "../session/client-bridge";
+import type {
+	ClientBridgeTerminalExitStatus,
+	ClientBridgeTerminalHandle,
+	ClientBridgeTerminalOutput,
+} from "../session/client-bridge";
 import { DEFAULT_MAX_BYTES, enforceInlineByteCap, streamTailUpdates, TailBuffer } from "../session/streaming-output";
 import { renderStatusLine } from "../tui";
 import { CachedOutputBlock, markFramedBlockComponent, outputBlockContentWidth } from "../tui/output-block";
@@ -51,6 +55,8 @@ export const BASH_DEFAULT_PREVIEW_LINES = DEFAULT_TERMINAL_PREVIEW_LINES;
 
 const BASH_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const DEFAULT_AUTO_BACKGROUND_THRESHOLD_MS = 60_000;
+const BASH_APPROVAL_SHELL_CONTROL_RE = /[\n\r;&|<>`$()]/u;
+const BASH_PATTERN_APPROVAL_VALUES = new Set(["allow", "deny", "prompt"]);
 
 /**
  * Shape a shell command line for an ACP-conformant `terminal/create` request.
@@ -127,6 +133,63 @@ export const CRITICAL_BASH_PATTERNS = [
 	/\bnc\b[^|;]*\s-[a-zA-Z]*[ec][a-zA-Z]*\s/i, // `nc -e` / `nc -c`.
 ] as const;
 
+type BashPatternApproval = "allow" | "deny" | "prompt";
+
+interface BashApprovalPatternRule {
+	match: string;
+	approval: BashPatternApproval;
+}
+
+function normalizeBashApprovalPattern(value: string): string {
+	return value.trim().replace(/\s+/gu, " ");
+}
+
+function bashApprovalPatternToRegExp(pattern: string): RegExp {
+	const escaped = normalizeBashApprovalPattern(pattern)
+		.split("*")
+		.map(part => part.replace(/[\\^$+?.()|[\]{}]/gu, "\\$&"))
+		.join(".*");
+	return new RegExp(`^${escaped}$`, "u");
+}
+
+function normalizeBashPatternApproval(value: unknown): BashPatternApproval | undefined {
+	if (typeof value !== "string") return undefined;
+	const normalized = value.trim().toLowerCase();
+	return BASH_PATTERN_APPROVAL_VALUES.has(normalized) ? (normalized as BashPatternApproval) : undefined;
+}
+
+function getBashApprovalPatternRules(value: unknown): BashApprovalPatternRule[] {
+	if (!Array.isArray(value)) return [];
+	return value
+		.map(item => {
+			if (!item || typeof item !== "object" || Array.isArray(item)) return undefined;
+			const record = item as Record<string, unknown>;
+			if (typeof record.match !== "string") return undefined;
+			const match = normalizeBashApprovalPattern(record.match);
+			const approval = normalizeBashPatternApproval(record.approval);
+			return match.length > 0 && approval ? { match, approval } : undefined;
+		})
+		.filter((rule): rule is BashApprovalPatternRule => !!rule);
+}
+
+function commandMatchesBashApprovalPattern(command: string, pattern: string): boolean {
+	const normalizedCommand = normalizeBashApprovalPattern(command);
+	if (normalizedCommand.length === 0) return false;
+	return bashApprovalPatternToRegExp(pattern).test(normalizedCommand);
+}
+
+function findBashApprovalPatternRule(
+	command: string,
+	rules: readonly BashApprovalPatternRule[],
+): BashApprovalPatternRule | undefined {
+	return rules.find(rule => {
+		if (rule.approval === "allow" && BASH_APPROVAL_SHELL_CONTROL_RE.test(command)) {
+			return false;
+		}
+		return commandMatchesBashApprovalPattern(command, rule.match);
+	});
+}
+
 async function saveBashOriginalArtifact(session: ToolSession, originalText: string): Promise<string | undefined> {
 	try {
 		const alloc = await session.allocateOutputArtifact?.("bash-original");
@@ -384,9 +447,29 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 	readonly approval = (args: unknown): ToolApprovalDecision => {
 		const rawCommand = (args as Partial<BashToolInput>).command;
 		const command = typeof rawCommand === "string" ? rawCommand : "";
+		const patternRules = getBashApprovalPatternRules(this.session.settings.get("bash.patterns"));
+		const patternRule = patternRules.find(rule => commandMatchesBashApprovalPattern(command, rule.match));
+		if (patternRule?.approval === "deny") {
+			return {
+				tier: "exec",
+				override: true,
+				policy: "deny",
+				reason: `Blocked by bash pattern: ${patternRule.match}`,
+			};
+		}
 		if (command !== "" && CRITICAL_BASH_PATTERNS.some(pattern => pattern.test(command))) {
 			return { tier: "exec", override: true, reason: "Critical pattern detected" };
 		}
+		const safePatternRule = findBashApprovalPatternRule(command, patternRules);
+		if (safePatternRule?.approval === "allow") return { tier: "write", policy: "allow" };
+		if (safePatternRule?.approval === "prompt") {
+			return {
+				tier: "exec",
+				override: true,
+				policy: "prompt",
+				reason: `Prompt required by bash pattern: ${safePatternRule.match}`,
+			};
+		}
 		return "exec";
 	};
 	readonly formatApprovalDetails = (args: unknown): string[] => {
@@ -703,28 +786,40 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		job: ManagedBashJobHandle,
 		thresholdMs: number,
 		signal?: AbortSignal,
-	): Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" }> {
+		steeringSignal?: AbortSignal,
+	): Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "steer" } | { kind: "aborted" }> {
 		if (signal?.aborted) {
 			return { kind: "aborted" };
 		}
+		if (steeringSignal?.aborted) {
+			return { kind: "steer" };
+		}
 
-		const waiters: Array<Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" }>> = [
-			job.completion,
-			Bun.sleep(thresholdMs).then(() => ({ kind: "running" as const })),
-		];
+		const waiters: Array<
+			Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "steer" } | { kind: "aborted" }>
+		> = [job.completion, Bun.sleep(thresholdMs).then(() => ({ kind: "running" as const }))];
 
-		if (!signal) {
+		if (!signal && !steeringSignal) {
 			return await Promise.race(waiters);
 		}
 
 		const { promise: abortedPromise, resolve: resolveAborted } = Promise.withResolvers<{ kind: "aborted" }>();
 		const onAbort = () => resolveAborted({ kind: "aborted" });
-		signal.addEventListener("abort", onAbort, { once: true });
-		waiters.push(abortedPromise);
+		const { promise: steerPromise, resolve: resolveSteer } = Promise.withResolvers<{ kind: "steer" }>();
+		const onSteer = () => resolveSteer({ kind: "steer" });
+		if (signal) {
+			signal.addEventListener("abort", onAbort, { once: true });
+			waiters.push(abortedPromise);
+		}
+		if (steeringSignal) {
+			steeringSignal.addEventListener("abort", onSteer, { once: true });
+			waiters.push(steerPromise);
+		}
 		try {
 			return await Promise.race(waiters);
 		} finally {
-			signal.removeEventListener("abort", onAbort);
+			signal?.removeEventListener("abort", onAbort);
+			steeringSignal?.removeEventListener("abort", onSteer);
 		}
 	}
 
@@ -911,7 +1006,12 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 			// foreground-wait cannot also be injected by the delivery loop. Lifted
 			// via resumeDeliveries() if we end up backgrounding after all.
 			autoBgManager.acknowledgeDeliveries([job.jobId]);
-			const waitResult = await this.#waitForManagedBashJob(job, autoBackgroundWaitMs, signal);
+			const waitResult = await this.#waitForManagedBashJob(
+				job,
+				autoBackgroundWaitMs,
+				signal,
+				ctx?.toolCall?.steeringSignal,
+			);
 			if (waitResult.kind === "completed") {
 				return waitResult.result;
 			}
@@ -924,52 +1024,94 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 			}
 			job.stopUpdates();
 			autoBgManager.resumeDeliveries([job.jobId]);
+			// "steer": a queued user/peer message arrived mid-wait — background
+			// the command (it keeps running) so the message injects promptly.
+			const notices =
+				waitResult.kind === "steer"
+					? [...pendingNotices, "Backgrounded early to handle an incoming message; the command keeps running."]
+					: pendingNotices;
 			return this.#buildBackgroundStartResult(job.jobId, job.getLatestText(), timeoutSec, {
 				requestedTimeoutSec,
-				notices: pendingNotices,
+				notices,
 			});
 		}
 
+		// Fold direnv/devenv env into (command, env) ONCE for the two backends
+		// that bypass `executeBash` — the ACP client terminal and the PTY. The
+		// `executeBash` branch below is intentionally excluded: it runs its own
+		// preflight internally, so routing the pre-applied command there too
+		// would double-apply the unset prefix and re-merge the env. No
+		// `commandPrefix` here: ACP applies the shell prefix via
+		// `wrapShellLineForClientTerminal`, and the PTY path never wrapped one.
+		// `callerTimeoutMs` clamps the direnv load to a positive command timeout
+		// (the backend's own timeout is installed only after this await), matching
+		// the executeBash branch so a cold `.envrc` can't outlast a short call.
+		const backendPreflight =
+			(clientBridge?.capabilities.terminal && clientBridge.createTerminal && !pty) ||
+			canUseInteractiveBashPty(pty, ctx)
+				? await applyDirenvPreflight(command, commandCwd, {
+						callerEnv: resolvedEnv,
+						signal,
+						timeoutMs: this.session.settings.get("bash.direnvLoadTimeoutMs"),
+						callerTimeoutMs: timeoutMs,
+						direnvSetting: this.session.settings.get("bash.direnv"),
+					})
+				: undefined;
+
 		// Route through the client terminal when the client advertises the terminal capability.
 		// Skip when pty=true (PTY needs the local terminal UI).
 		if (clientBridge?.capabilities.terminal && clientBridge.createTerminal && !pty) {
-			const bridgeWallTimeStart = performance.now();
-			const shellSpawn = wrapShellLineForClientTerminal(command, this.session.settings.getShellConfig());
-			const handle = await clientBridge.createTerminal({
-				command: shellSpawn.command,
-				args: shellSpawn.args,
-				cwd: commandCwd,
-				env: resolvedEnv
-					? Object.entries(resolvedEnv).map(([name, value]) => ({ name, value: value as string }))
-					: undefined,
-				outputByteLimit: DEFAULT_MAX_BYTES,
-			});
-
-			// Emit partial update so the editor can embed the live terminal card.
-			onUpdate?.({ content: [], details: { terminalId: handle.terminalId } });
-
-			const exitPromise = handle.waitForExit();
-			let exitStatus!: ClientBridgeTerminalExitStatus;
-
-			type BridgeRaceResult =
-				| { kind: "exit"; status: ClientBridgeTerminalExitStatus }
-				| { kind: "poll" }
-				| { kind: "timeout" }
-				| { kind: "aborted" };
+			// Invariant (ACP terminal bridge): createTerminal has no signal in its
+			// contract; allocation cannot be cancelled retroactively. Guard before
+			// allocation. Shared timeout helper / pure AbortSignal fusion rejected:
+			// we need explicit kill-before-read ordering and distinct abort vs
+			// timeout result shapes. Per-route race retained for testability.
+			if (signal?.aborted) {
+				throw new ToolAbortError("Command aborted");
+			}
 
-			// Set up abort listener before entering the poll loop. The listener
-			// kicks off `handle.kill()` synchronously so a `session/cancel`
-			// arriving mid-poll terminates the remote command immediately,
-			// instead of waiting for the next `currentOutput()` to return.
+			const bridgeWallTimeStart = performance.now();
+			const killGraceMs = 1000;
+			const outputSnapshotGraceMs = 2000;
+			// Cancellable timeout: a bare Bun.sleep(timeoutMs) would leave a live,
+			// ref'd timer for the full command timeout after fast completions —
+			// accumulating timers and delaying process shutdown in SDK/headless use.
+			// `timeoutMs` is optional (#4642): without one, no timer is armed and
+			// the promise simply never resolves.
+			const { promise: timeoutPromise, resolve: resolveTimeout } = Promise.withResolvers<{
+				kind: "timeout";
+			}>();
+			const timeoutTimer = timeoutMs ? setTimeout(() => resolveTimeout({ kind: "timeout" }), timeoutMs) : undefined;
 			const { promise: abortedP, resolve: resolveAborted } = Promise.withResolvers<void>();
+			let handle: ClientBridgeTerminalHandle | undefined;
 			let killStarted = false;
 			const fireKill = (): Promise<void> => {
 				if (killStarted) return Promise.resolve();
+				const currentHandle = handle;
+				if (!currentHandle) return Promise.resolve();
 				killStarted = true;
-				return handle.kill().catch((error: unknown) => {
-					logger.warn("ACP terminal kill failed", { terminalId: handle.terminalId, error });
+				return currentHandle.kill().catch((error: unknown) => {
+					logger.warn("ACP terminal kill failed", { terminalId: currentHandle.terminalId, error });
 				});
 			};
+			const cleanupLateCreate = (createP: Promise<ClientBridgeTerminalHandle>): void => {
+				void createP
+					.then(async lateHandle => {
+						try {
+							await lateHandle.kill();
+						} catch (error) {
+							logger.warn("ACP terminal kill failed", { terminalId: lateHandle.terminalId, error });
+						}
+						try {
+							await lateHandle.release();
+						} catch (error) {
+							logger.warn("ACP terminal release failed", { terminalId: lateHandle.terminalId, error });
+						}
+					})
+					.catch((error: unknown) => {
+						logger.warn("ACP terminal create failed after cancellation", { error });
+					});
+			};
 			const onAbortSignal = () => {
 				resolveAborted();
 				void fireKill();
@@ -977,90 +1119,150 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 			signal?.addEventListener("abort", onAbortSignal, { once: true });
 
 			try {
-				try {
-					if (signal?.aborted) {
-						await fireKill();
-						throw new ToolAbortError("Command aborted");
-					}
+				// direnv-transformed command (carries any `unset -v` prefix) + merged
+				// env; falls back to the raw command/env when direnv is off/absent.
+				const bridgeCommand = backendPreflight?.command ?? command;
+				const bridgeEnv = backendPreflight?.env ?? resolvedEnv;
+				const shellSpawn = wrapShellLineForClientTerminal(bridgeCommand, this.session.settings.getShellConfig());
+				const createP = clientBridge.createTerminal({
+					command: shellSpawn.command,
+					args: shellSpawn.args,
+					cwd: commandCwd,
+					env: bridgeEnv
+						? Object.entries(bridgeEnv).map(([name, value]) => ({ name, value: value as string }))
+						: undefined,
+					outputByteLimit: DEFAULT_MAX_BYTES,
+				});
+				const createRaced = await Promise.race([
+					createP.then(createdHandle => ({ kind: "created" as const, handle: createdHandle })),
+					timeoutPromise,
+					abortedP.then(() => ({ kind: "aborted" as const })),
+				]);
+				if (createRaced.kind === "aborted" || signal?.aborted) {
+					cleanupLateCreate(createP);
+					throw new ToolAbortError("Command aborted");
+				}
+				if (createRaced.kind === "timeout") {
+					cleanupLateCreate(createP);
+					const timedOutResult: BashInteractiveResult = {
+						output: "",
+						exitCode: undefined,
+						cancelled: false,
+						timedOut: true,
+						truncated: false,
+						totalLines: 0,
+						totalBytes: 0,
+						outputLines: 0,
+						outputBytes: 0,
+					};
+					this.#throwIfUnfinished(timedOutResult, timeoutSec, this.#formatResultOutput(timedOutResult));
+					throw new ToolError("Command timed out");
+				}
 
-					const timeoutPromise = timeoutMs
-						? Bun.sleep(timeoutMs).then(() => ({ kind: "timeout" as const }))
-						: undefined;
-					// Poll until the process exits, times out, or the caller aborts.
-					for (;;) {
-						const racers: Array<Promise<BridgeRaceResult>> = [
-							exitPromise.then(s => ({ kind: "exit" as const, status: s })),
-							Bun.sleep(250).then(() => ({ kind: "poll" as const })),
-						];
-						if (timeoutPromise) racers.push(timeoutPromise);
-						if (signal) {
-							racers.push(abortedP.then(() => ({ kind: "aborted" as const })));
-						}
-						const raced = await Promise.race(racers);
+				handle = createRaced.handle;
+
+				// Emit partial update so the editor can embed the live terminal card.
+				onUpdate?.({ content: [], details: { terminalId: handle.terminalId } });
+
+				const exitPromise = handle.waitForExit();
+				let exitStatus!: ClientBridgeTerminalExitStatus;
+
+				type BridgeRaceResult =
+					| { kind: "exit"; status: ClientBridgeTerminalExitStatus }
+					| { kind: "poll" }
+					| { kind: "timeout" }
+					| { kind: "aborted" };
+
+				const exitRacer = exitPromise.then(status => ({ kind: "exit" as const, status }));
+				const abortRacer = abortedP.then(() => ({ kind: "aborted" as const }));
+				const abortPollRacer = abortedP.then(() => undefined as ClientBridgeTerminalOutput | undefined);
+				const timeoutPollRacer = timeoutPromise.then(() => undefined as ClientBridgeTerminalOutput | undefined);
+				let lastPolledOutput: ClientBridgeTerminalOutput = { output: "", truncated: false };
+
+				// Poll until the process exits, times out, or the caller aborts.
+				for (;;) {
+					const racers: Array<Promise<BridgeRaceResult>> = [
+						exitRacer,
+						timeoutPromise,
+						Bun.sleep(250).then(() => ({ kind: "poll" as const })),
+					];
+					if (signal) {
+						racers.push(abortRacer);
+					}
+					const raced = await Promise.race(racers);
 
-						if (raced.kind === "aborted" || signal?.aborted) {
-							await fireKill();
-							throw new ToolAbortError("Command aborted");
-						}
+					if (raced.kind === "aborted" || signal?.aborted) {
+						await Promise.race([fireKill(), Bun.sleep(killGraceMs)]);
+						throw new ToolAbortError("Command aborted");
+					}
 
-						if (raced.kind === "timeout") {
-							// Kill before reading final output so a slow `terminal/output`
-							// RPC cannot let a timed-out command keep running past the
-							// enforced timeout. The handle stays valid post-kill so the
-							// buffered output is still readable.
-							await fireKill();
-							let current = { output: "", truncated: false };
-							try {
-								current = await handle.currentOutput();
-							} catch (error) {
-								logger.warn("ACP terminal final output read failed", {
-									terminalId: handle.terminalId,
-									error,
-								});
-							}
-							const timedOutResult: BashInteractiveResult = {
-								output: current.output,
-								exitCode: undefined,
-								cancelled: false,
-								timedOut: true,
-								truncated: current.truncated,
-								totalLines: current.output.length > 0 ? current.output.split("\n").length : 0,
-								totalBytes: current.output.length,
-								outputLines: current.output.length > 0 ? current.output.split("\n").length : 0,
-								outputBytes: current.output.length,
-							};
-							this.#throwIfUnfinished(timedOutResult, timeoutSec, this.#formatResultOutput(timedOutResult));
-							throw new ToolError("Command timed out");
+					if (raced.kind === "timeout") {
+						// Kill before reading final output so a slow `terminal/output`
+						// RPC cannot let a timed-out command keep running past the
+						// enforced timeout. The handle stays valid post-kill so the
+						// buffered output is still readable.
+						await Promise.race([fireKill(), Bun.sleep(killGraceMs)]);
+						let current = lastPolledOutput;
+						try {
+							current = await Promise.race([
+								handle.currentOutput(),
+								Bun.sleep(outputSnapshotGraceMs).then(() => lastPolledOutput),
+							]);
+						} catch (error) {
+							logger.warn("ACP terminal final output read failed", {
+								terminalId: handle.terminalId,
+								error,
+							});
 						}
+						const timedOutResult: BashInteractiveResult = {
+							output: current.output,
+							exitCode: undefined,
+							cancelled: false,
+							timedOut: true,
+							truncated: current.truncated,
+							totalLines: current.output.length > 0 ? current.output.split("\n").length : 0,
+							totalBytes: current.output.length,
+							outputLines: current.output.length > 0 ? current.output.split("\n").length : 0,
+							outputBytes: current.output.length,
+						};
+						this.#throwIfUnfinished(timedOutResult, timeoutSec, this.#formatResultOutput(timedOutResult));
+						throw new ToolError("Command timed out");
+					}
 
-						if (raced.kind === "exit") {
-							exitStatus = raced.status;
-							break;
-						}
+					if (raced.kind === "exit") {
+						exitStatus = raced.status;
+						break;
+					}
 
-						// Poll tick: push current output so agent-loop transcript stays consistent.
-						// Race the read against abort so a stuck `terminal/output` RPC does not
-						// delay cancellation.
-						const pollOutput = await Promise.race([
-							handle.currentOutput(),
-							abortedP.then(() => undefined as ClientBridgeTerminalOutput | undefined),
-						]);
-						if (pollOutput === undefined) {
-							// Abort fired during the poll-tick read; let the next loop iteration
-							// observe `signal?.aborted` and exit via the abort branch.
-							continue;
-						}
-						onUpdate?.({
-							content: [{ type: "text", text: pollOutput.output }],
-							details: { terminalId: handle.terminalId },
-						});
+					// Poll tick: push current output so agent-loop transcript stays consistent.
+					// Race the read against abort/timeout so a stuck `terminal/output` RPC does
+					// not delay cancellation or let the command outlive its deadline.
+					const pollOutput = await Promise.race([handle.currentOutput(), abortPollRacer, timeoutPollRacer]);
+					if (pollOutput === undefined) {
+						// Abort or timeout fired during the poll-tick read; let the next loop
+						// iteration exit via the matching abort/timeout branch.
+						continue;
 					}
-				} finally {
-					signal?.removeEventListener("abort", onAbortSignal);
+					lastPolledOutput = pollOutput;
+					onUpdate?.({
+						content: [{ type: "text", text: pollOutput.output }],
+						details: { terminalId: handle.terminalId },
+					});
 				}
 
 				// Fetch final output; the terminal is released in the outer finally.
-				const finalOutput = await handle.currentOutput();
+				let finalOutput = lastPolledOutput;
+				try {
+					finalOutput = await Promise.race([
+						handle.currentOutput(),
+						Bun.sleep(outputSnapshotGraceMs).then(() => lastPolledOutput),
+					]);
+				} catch (error) {
+					logger.warn("ACP terminal final output read failed", {
+						terminalId: handle.terminalId,
+						error,
+					});
+				}
 
 				// Map exit status: null exitCode with a signal → treat as signal kill (137).
 				const rawExitCode = exitStatus.exitCode;
@@ -1093,10 +1295,18 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 					wallTimeMs: performance.now() - bridgeWallTimeStart,
 				});
 			} finally {
-				try {
-					await handle.release();
-				} catch (error) {
-					logger.warn("ACP terminal release failed", { terminalId: handle.terminalId, error });
+				clearTimeout(timeoutTimer);
+				signal?.removeEventListener("abort", onAbortSignal);
+				if (handle) {
+					const releaseHandle = handle;
+					// Bound release like kill/output: a hung `terminal/release` RPC must not
+					// keep the tool pending after the result is already decided.
+					await Promise.race([
+						releaseHandle.release().catch((error: unknown) => {
+							logger.warn("ACP terminal release failed", { terminalId: releaseHandle.terminalId, error });
+						}),
+						Bun.sleep(killGraceMs),
+					]);
 				}
 			}
 		}
@@ -1114,15 +1324,21 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		const wallTimeStart = performance.now();
 		const result: BashResult | BashInteractiveResult = interactiveUi
 			? await runInteractiveBashPty(interactiveUi, {
-					command,
+					// PTY bypasses executeBash, so feed it the direnv-transformed
+					// command + merged env (backendPreflight is defined whenever this
+					// branch runs, since both gate on canUseInteractiveBashPty).
+					command: backendPreflight?.command ?? command,
 					cwd: commandCwd,
 					timeoutMs,
 					signal,
-					env: resolvedEnv,
+					env: backendPreflight?.env ?? resolvedEnv,
 					artifactPath,
 					artifactId,
 				})
-			: await executeBash(command, {
+			: // executeBash runs its OWN direnv preflight internally — pass the RAW
+				// command + resolvedEnv here so the unset prefix / env merge is not
+				// applied twice.
+				await executeBash(command, {
 					cwd: commandCwd,
 					sessionKey: this.session.getSessionId?.() ?? undefined,
 					timeout: timeoutMs ?? 0,

package/src/tools/browser/launch.ts

@@ -275,9 +275,14 @@ function resolveSystemChromium(): string | undefined {
 	return undefined;
 }
 
+/** Options shared by headless Chromium consumers. */
 export interface LaunchHeadlessOptions {
 	headless: boolean;
 	viewport?: { width: number; height: number; deviceScaleFactor?: number };
+	/** Additional Chromium arguments merged with the centralized launch defaults. */
+	args?: readonly string[];
+	/** Additional exact Puppeteer default arguments to suppress. */
+	ignoreDefaultArgs?: readonly string[];
 }
 
 export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<Browser> {
@@ -308,13 +313,16 @@ export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promis
 	if (ignoreCert === "true" || ignoreCert === "1" || ignoreCert === "yes" || ignoreCert === "on") {
 		launchArgs.push("--ignore-certificate-errors");
 	}
+	for (const arg of opts.args ?? []) {
+		if (!launchArgs.includes(arg)) launchArgs.push(arg);
+	}
 	const executablePath = await ensureChromiumExecutable();
 	return await puppeteer.launch({
 		headless: opts.headless,
 		defaultViewport: opts.headless ? initialViewport : null,
 		executablePath,
 		args: launchArgs,
-		ignoreDefaultArgs: stealthIgnoreDefaultArgs(executablePath),
+		ignoreDefaultArgs: [...new Set([...stealthIgnoreDefaultArgs(executablePath), ...(opts.ignoreDefaultArgs ?? [])])],
 		protocolTimeout: BROWSER_PROTOCOL_TIMEOUT_MS,
 	});
 }

package/src/tools/browser/tab-supervisor.ts

@@ -286,13 +286,16 @@ async function acquireTabImpl(
 		}
 	}
 
-	// If the caller aborted while we were spawning/initializing the worker,
-	// tear the freshly-built worker down before publishing the tab so the
-	// browser refCount (which `holdBrowser` below would take) never grows for
-	// a tab nobody is waiting for.
+	// If the caller aborted while we were spawning/initializing the worker, tear
+	// the freshly-built worker down before publishing the tab so the browser
+	// refCount (which `holdBrowser` below would take) never grows for a tab
+	// nobody is waiting for. Mirror the error paths' `refCount === 0` release so
+	// a fresh browser held by nothing but this aborted open is not orphaned in
+	// the registry; a browser still leased/held elsewhere (refCount > 0) is left
+	// for its owner to release.
 	if (opts.signal?.aborted) {
 		await worker.terminate().catch(() => undefined);
-		if (tempHold) await releaseBrowser(browser, { kill: false }).catch(() => undefined);
+		if (tempHold || browser.refCount === 0) await releaseBrowser(browser, { kill: false }).catch(() => undefined);
 		throw new ToolAbortError("Browser tab open aborted");
 	}