@gajae-code/coding-agent 0.16.0 → 0.16.3

package/src/tools/bash.ts

@@ -5,7 +5,7 @@ import type { Component } from "@gajae-code/tui";
 import { getKeybindings, ImageProtocol, TERMINAL, Text, visibleWidth } from "@gajae-code/tui";
 import { getProjectDir, isEnoent, logger, prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
-import { AsyncJobManager } from "../async";
+import { AsyncJobManager, type FoldReason } from "../async";
 import { type BashArtifactSaveResult, type BashResult, executeBash } from "../exec/bash-executor";
 
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
@@ -25,6 +25,7 @@ import type {
 	ClientBridgeTerminalHandle,
 	ClientBridgeTerminalOutput,
 } from "../session/client-bridge";
+import type { FoldAdapter } from "../session/fold-coordinator";
 import {
 	DEFAULT_ARTIFACT_MAX_BYTES,
 	OutputSink,
@@ -85,6 +86,18 @@ function sliceTextAfterUtf8ByteOffset(text: string, offsetBytes: number): string
 import { clampTimeout, TOOL_TIMEOUTS } from "./tool-timeouts";
 
 export const BASH_DEFAULT_PREVIEW_LINES = 10;
+/**
+ * A user steer folds a running foreground bash call only after it has been
+ * running at least this long. Shorter commands finish normally and the steer is
+ * consumed at the ordinary tool boundary, so a quick `git status` never turns
+ * into a background job plus a wake-up turn.
+ */
+export const STEER_FOLD_GRACE_MS = 2_000;
+
+/** Model-facing line appended to a steer-folded background-start result. */
+export function steerFoldReasonLine(jobId: string): string {
+	return `Folded into background job ${jobId} because a user steer arrived; the command keeps running with its original timeout and its result will wake a later turn.`;
+}
 
 const BASH_ERROR_MAX_BYTES = 4096;
 const ARTIFACT_SAVE_DIAGNOSTIC_MAX_BYTES = 256;
@@ -488,6 +501,8 @@ export interface BashToolDetails {
 	timeoutSeconds?: number;
 	requestedTimeoutSeconds?: number;
 	terminalId?: string;
+	/** Why the foreground wait was folded, when this result is a background-start after a fold. */
+	foldReason?: FoldReason;
 	async?: {
 		state: "running" | "completed" | "failed";
 		jobId: string;
@@ -934,7 +949,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		label: string,
 		previewText: string,
 		timeoutSec: number,
-		options: { requestedTimeoutSec?: number; notices?: readonly string[]; terminalId?: string } = {},
+		options: {
+			requestedTimeoutSec?: number;
+			notices?: readonly string[];
+			terminalId?: string;
+			foldReason?: FoldReason;
+		} = {},
 	): AgentToolResult<BashToolDetails> {
 		const details: BashToolDetails = {
 			timeoutSeconds: timeoutSec,
@@ -946,6 +966,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (options.requestedTimeoutSec !== undefined && options.requestedTimeoutSec !== timeoutSec) {
 			details.requestedTimeoutSeconds = options.requestedTimeoutSec;
 		}
+		if (options.foldReason !== undefined) details.foldReason = options.foldReason;
 		const lines: string[] = [];
 		const trimmedPreview = previewText.trimEnd();
 		if (trimmedPreview.length > 0) {
@@ -955,6 +976,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			lines.push(...options.notices, "");
 		}
 		lines.push(`Background job ${jobId} started: ${label}`);
+		if (options.foldReason === "steer") lines.push(steerFoldReasonLine(jobId));
 		lines.push("Result will be delivered automatically when complete.");
 		lines.push(
 			`You can use \`job\` to poll until complete, but prefer to continue with another task in the meanwhile if it's not blocking.`,
@@ -1115,24 +1137,109 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		return AsyncJobManager.forEndpoint(endpointId) ?? AsyncJobManager.instance();
 	}
 
+	/**
+	 * Whether a queued user steer may fold the running foreground wait. Mirrors
+	 * the loop's steer admission: `busyPromptMode=queue` never admits a steer
+	 * into the busy run, so it never folds. `toolInterruptPolicy` is
+	 * deliberately NOT a gate: `finish_tools` means "do not kill the batch to
+	 * deliver a steer", and a fold kills nothing. It is the one way to deliver
+	 * the steer now AND let the command finish, so it applies under both
+	 * policies; the policy only decides what the loop does with sibling tools
+	 * after the fold returns. The auto-background setting is likewise not
+	 * consulted: like the chord, a steer fold is a user action.
+	 *
+	 * Fails closed: a session that cannot report newly admitted steering or
+	 * accept a fold request is not steer-foldable.
+	 */
+	#steerFoldEnabled(): boolean {
+		const { waitForUserSteering, requestForegroundBashBackground } = this.session;
+		if (!waitForUserSteering || !requestForegroundBashBackground) return false;
+		return this.session.settings.get("busyPromptMode") === "steer";
+	}
+
+	/**
+	 * Fold `adapter` on the first user steer that ARRIVES after the wait has run
+	 * for {@link STEER_FOLD_GRACE_MS} since `startedAt`. A steer already queued
+	 * when the wait starts, or one that arrives inside the grace window, never
+	 * folds: the command finishes normally and that steer is consumed at the
+	 * ordinary tool boundary. The watcher keeps observing so a later qualifying
+	 * steer still folds, and re-checks the gate at that moment so a
+	 * `busyPromptMode` change during the command is honored.
+	 * Returns a stop function; call it when the wait settles. No-op when steer
+	 * folding is gated off at start.
+	 */
+	#watchSteerForFold(adapter: FoldAdapter, startedAt: number): () => void {
+		if (!this.#steerFoldEnabled()) return () => {};
+		const waitForSteer = this.session.waitForUserSteering;
+		const requestFold = this.session.requestForegroundBashBackground;
+		if (!waitForSteer || !requestFold) return () => {};
+		const watch = new AbortController();
+		const observe = async (): Promise<void> => {
+			while (!watch.signal.aborted) {
+				await waitForSteer(watch.signal);
+				if (watch.signal.aborted) return;
+				if (Date.now() - startedAt < STEER_FOLD_GRACE_MS) continue;
+				if (!this.#steerFoldEnabled()) continue;
+				await requestFold("steer", adapter);
+				return;
+			}
+		};
+		observe().catch((error: unknown) => {
+			logger.warn("Steer-triggered fold failed", {
+				jobId: adapter.jobId,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		});
+		return () => watch.abort();
+	}
+
+	/**
+	 * Race a managed job against the auto-background threshold, an explicit fold
+	 * (chord / SDK control / steer), and abort. A steer that arrives once the
+	 * command has run for {@link STEER_FOLD_GRACE_MS} requests a `steer` fold,
+	 * which settles this wait through the same `backgroundRequest` path as the
+	 * chord; a steer inside the grace window is ignored here and consumed at the
+	 * ordinary tool boundary once the command finishes.
+	 */
 	async #waitForManagedBashJob(
 		job: ManagedBashJobHandle,
 		thresholdMs: number,
 		signal?: AbortSignal,
-		backgroundRequest?: Promise<void>,
-	): Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" }> {
+		backgroundRequest?: Promise<FoldReason>,
+		foldAdapter?: FoldAdapter,
+	): Promise<ManagedBashJobCompletion | { kind: "running"; reason: FoldReason } | { kind: "aborted" }> {
 		if (signal?.aborted) {
 			return { kind: "aborted" };
 		}
 
-		const threshold = Promise.withResolvers<{ kind: "running" }>();
-		const thresholdTimer = setTimeout(() => threshold.resolve({ kind: "running" }), Math.max(0, thresholdMs));
-		const waiters: Array<Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" }>> = [
-			job.completion,
-			threshold.promise,
-		];
+		const startedAt = Date.now();
+		const threshold = Promise.withResolvers<{ kind: "running"; reason: FoldReason }>();
+		const thresholdTimer = setTimeout(
+			() => {
+				const requestFold = this.session.requestForegroundBashBackground;
+				if (!foldAdapter || !requestFold) {
+					threshold.resolve({ kind: "running", reason: "timer" });
+					return;
+				}
+				void requestFold("timer", foldAdapter)
+					.then(folded => {
+						if (!folded) threshold.resolve({ kind: "running", reason: "timer" });
+					})
+					.catch(error => {
+						logger.warn("Timer-triggered fold failed", {
+							jobId: foldAdapter.jobId,
+							error: error instanceof Error ? error.message : String(error),
+						});
+						threshold.resolve({ kind: "running", reason: "timer" });
+					});
+			},
+			Math.max(0, thresholdMs),
+		);
+		const waiters: Array<
+			Promise<ManagedBashJobCompletion | { kind: "running"; reason: FoldReason } | { kind: "aborted" }>
+		> = [job.completion, threshold.promise];
 		if (backgroundRequest) {
-			waiters.push(backgroundRequest.then(() => ({ kind: "running" as const })));
+			waiters.push(backgroundRequest.then(reason => ({ kind: "running" as const, reason })));
 		}
 
 		let onAbort: (() => void) | undefined;
@@ -1142,9 +1249,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			signal.addEventListener("abort", onAbort, { once: true });
 			waiters.push(aborted.promise);
 		}
+
+		const stopSteerWatch =
+			backgroundRequest && foldAdapter ? this.#watchSteerForFold(foldAdapter, startedAt) : () => {};
 		try {
 			return await Promise.race(waiters);
 		} finally {
+			stopSteerWatch();
 			clearTimeout(thresholdTimer);
 			if (signal && onAbort) signal.removeEventListener("abort", onAbort);
 		}
@@ -1657,7 +1768,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			});
 			const jobGeneration = asyncManager.getJob(job.jobId)?.generation ?? job.jobId;
 			job.setBackgrounded(true);
-			asyncManager.markBackgrounded(job.jobId, jobGeneration);
+			asyncManager.markStartedInBackground(job.jobId, jobGeneration);
 			return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
@@ -1711,13 +1822,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			const jobGeneration = ownedManager.getJob(job.jobId)?.generation ?? job.jobId;
 			if (startBackgrounded) {
 				job.setBackgrounded(true);
-				ownedManager.markBackgrounded(job.jobId, jobGeneration);
+				ownedManager.markStartedInBackground(job.jobId, jobGeneration);
 				return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
 					requestedTimeoutSec,
 					notices: pendingNotices,
 				});
 			}
-			const backgroundRequest = Promise.withResolvers<void>();
+			const backgroundRequest = Promise.withResolvers<FoldReason>();
 			// Exactly one party may settle the foreground caller. detachObserver (the
 			// fold won) and resolveForegroundObserver (a completion was handed back
 			// after a failed fold) share this flag, so a race cannot double-settle.
@@ -1727,7 +1838,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				foregroundSettled = true;
 				return "resolved";
 			};
-			const unregisterBackgroundRequest = this.session.registerForegroundFoldParticipant?.({
+			const managedFoldAdapter: FoldAdapter = {
 				kind: "bash-managed",
 				jobId: job.jobId,
 				jobGeneration,
@@ -1746,24 +1857,26 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					const current = ownedManager.getJob(job.jobId);
 					return current?.generation === jobGeneration ? current : undefined;
 				},
-				detachObserver: () => {
+				detachObserver: receipt => {
 					const outcome = settleForeground();
 					if (outcome === "resolved") {
 						job.setBackgrounded(true);
-						ownedManager.markBackgrounded(job.jobId, jobGeneration);
-						backgroundRequest.resolve();
+						ownedManager.markBackgrounded(job.jobId, jobGeneration, receipt.reason);
+						backgroundRequest.resolve(receipt.reason);
 					}
 					return outcome;
 				},
 				resolveForegroundObserver: () => settleForeground(),
-			});
-			let waitResult: ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" };
+			};
+			const unregisterBackgroundRequest = this.session.registerForegroundFoldParticipant?.(managedFoldAdapter);
+			let waitResult: ManagedBashJobCompletion | { kind: "running"; reason: FoldReason } | { kind: "aborted" };
 			try {
 				waitResult = await this.#waitForManagedBashJob(
 					job,
 					autoBackgroundWaitMs,
 					signal,
 					backgroundRequest.promise,
+					managedFoldAdapter,
 				);
 			} finally {
 				unregisterBackgroundRequest?.();
@@ -1791,10 +1904,11 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				throw new ToolAbortError(formatManagedAbortFailure(undefined, undefined, job.getLatestText()));
 			}
 			job.setBackgrounded(true);
-			ownedManager.markBackgrounded(job.jobId, jobGeneration);
+			ownedManager.markBackgrounded(job.jobId, jobGeneration, waitResult.reason);
 			return this.#buildBackgroundStartResult(job.jobId, job.label, job.getLatestText(), timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
+				foldReason: waitResult.reason,
 			});
 		}
 
@@ -2323,9 +2437,9 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			void bridgeHandle.completion.finally(unregisterOwnerCleanup);
 			registerOwnedIfLineaged(bridgeManager, toolCallId, bridgeJobId, bridgeEndpointId);
 
-			const bridgeFoldRequest = Promise.withResolvers<void>();
+			const bridgeFoldRequest = Promise.withResolvers<FoldReason>();
 			const bridgeOriginatingTurn = ctx?.attemptScope !== undefined;
-			const unregisterBridgeFold = this.session.registerForegroundFoldParticipant?.({
+			const bridgeFoldAdapter: FoldAdapter = {
 				kind: "client-terminal",
 				jobId: bridgeJobId,
 				jobGeneration: bridgeGeneration,
@@ -2342,25 +2456,27 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					const current = bridgeManager.getJob(bridgeJobId);
 					return current?.generation === bridgeGeneration ? current : undefined;
 				},
-				detachObserver: () => {
+				detachObserver: receipt => {
 					const outcome = settleBridgeForeground();
 					if (outcome === "resolved") {
 						bridgeHandle.setBackgrounded(true);
-						bridgeManager.markBackgrounded(bridgeJobId, bridgeGeneration);
-						bridgeFoldRequest.resolve();
+						bridgeManager.markBackgrounded(bridgeJobId, bridgeGeneration, receipt.reason);
+						bridgeFoldRequest.resolve(receipt.reason);
 					}
 					return outcome;
 				},
 				resolveForegroundObserver: () => settleBridgeForeground(),
-			});
+			};
+			const unregisterBridgeFold = this.session.registerForegroundFoldParticipant?.(bridgeFoldAdapter);
 
-			let bridgeWait: ManagedBashJobCompletion | { kind: "running" } | { kind: "aborted" };
+			let bridgeWait: ManagedBashJobCompletion | { kind: "running"; reason: FoldReason } | { kind: "aborted" };
 			try {
 				bridgeWait = await this.#waitForManagedBashJob(
 					bridgeHandle,
 					this.#autoBackgroundEnabled ? this.#resolveAutoBackgroundWaitMs(timeoutMs) : timeoutMs + 1_000,
 					signal,
 					bridgeFoldRequest.promise,
+					bridgeFoldAdapter,
 				);
 			} finally {
 				unregisterBridgeFold?.();
@@ -2395,11 +2511,12 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			// Folded (or auto-backgrounded): the remote terminal keeps running and its
 			// result arrives as a background completion.
 			bridgeHandle.setBackgrounded(true);
-			bridgeManager.markBackgrounded(bridgeJobId, bridgeGeneration);
+			bridgeManager.markBackgrounded(bridgeJobId, bridgeGeneration, bridgeWait.reason);
 			return this.#buildBackgroundStartResult(bridgeJobId, bridgeLabel, bridgeHandle.getLatestText(), timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
 				terminalId: handle.terminalId,
+				foldReason: bridgeWait.reason,
 			});
 		}
 
@@ -2521,7 +2638,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 							},
 						);
 						void controls.terminalCompletion.finally(unregisterPtyOwnerCleanup);
-						ptyFoldUnregister = this.session.registerForegroundFoldParticipant?.({
+						const ptyStartedAt = Date.now();
+						const ptyFoldAdapter: FoldAdapter = {
 							kind: "bash-pty",
 							jobId: ptyJobId,
 							jobGeneration: ptyGeneration,
@@ -2538,12 +2656,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 								const current = ptyManager.getJob(ptyJobId);
 								return current?.generation === ptyGeneration ? current : undefined;
 							},
-							detachObserver: () => {
+							detachObserver: receipt => {
 								// Output-only continuation: stdin forwarding ends here and the
 								// process is never killed or restarted by folding.
 								const started = this.#buildBackgroundStartResult(ptyJobId, ptyLabel, "", timeoutSec, {
 									requestedTimeoutSec,
 									notices: pendingNotices,
+									foldReason: receipt.reason,
 								});
 								const outcome = controls.detachObserver(
 									interactiveResultFromText(this.#extractTextResult(started)),
@@ -2551,13 +2670,19 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 								if (outcome === "resolved") {
 									controls.detachForegroundCancellation();
 									ptyBackgrounded = true;
-									ptyManager.markBackgrounded(ptyJobId, ptyGeneration);
+									ptyManager.markBackgrounded(ptyJobId, ptyGeneration, receipt.reason);
 									ptyFoldResult = started;
 								}
 								return outcome;
 							},
 							resolveForegroundObserver: () => "already-settled",
-						});
+						};
+						const unregisterPtyFold = this.session.registerForegroundFoldParticipant?.(ptyFoldAdapter);
+						const stopPtySteerWatch = this.#watchSteerForFold(ptyFoldAdapter, ptyStartedAt);
+						ptyFoldUnregister = () => {
+							stopPtySteerWatch();
+							unregisterPtyFold?.();
+						};
 					},
 					onFoldKey: () => {
 						const now = Date.now();

package/src/tools/browser/launch.ts

@@ -293,6 +293,43 @@ function resolveSystemChromium(): string | undefined {
 	return found;
 }
 
+export function resolveSystemChromiumForTest(): string | undefined {
+	return resolveSystemChromium();
+}
+
+export function resetSystemChromiumForTest(): void {
+	resolvedChromium = undefined;
+}
+
+export function headlessExecutableForProfileReuse(): string | undefined {
+	return resolveSystemChromium() ?? trustedBrowserEnv("PUPPETEER_EXECUTABLE_PATH");
+}
+
+/**
+ * On macOS the Cookies DB is encrypted with a Keychain key whose service name is
+ * brand-specific ("Chrome Safe Storage" vs "Chromium Safe Storage"). A Chrome profile
+ * copied into a bundled Chromium therefore decrypts to garbage with no warning.
+ * Return true only when the headless executable can actually decrypt the discovered profile.
+ */
+export function canDecryptProfileCookies(
+	executablePath: string | undefined,
+	discoveredUserDataDir: string | undefined,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (platform !== "darwin") return true;
+	if (!discoveredUserDataDir) return true;
+	if (!executablePath) return false;
+	const lowerExe = executablePath.toLowerCase();
+	const lowerDir = discoveredUserDataDir.toLowerCase();
+	const isChromiumExe = lowerExe.includes("chromium");
+	const isChromeExe = lowerExe.includes("google chrome") || lowerExe.includes("/google/chrome");
+	const isChromiumProfile = lowerDir.includes("chromium");
+	const isChromeProfile = lowerDir.includes("google") && lowerDir.includes("chrome");
+	if (isChromeProfile && isChromiumExe && !isChromeExe) return false;
+	if (isChromiumProfile && isChromeExe) return false;
+	return true;
+}
+
 /** Edge is Chromium-based but keeps its own profile format under its own user data root. */
 const EDGE_EXECUTABLE_PATTERN =
 	/(?:^|[/\\])(?:msedge(?:\.exe)?|microsoft-edge(?:-(?:stable|beta|dev|canary))?|com\.microsoft\.Edge|Microsoft Edge(?: Beta| Dev| Canary)?)$/i;

package/src/tools/browser/registry.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { logger } from "@gajae-code/utils";
 import type { Subprocess } from "bun";
@@ -12,7 +13,14 @@ import {
 	killExistingByPath,
 	waitForCdp,
 } from "./attach";
-import { BROWSER_PROTOCOL_TIMEOUT_MS, launchHeadlessBrowser, loadPuppeteer, type UserAgentOverride } from "./launch";
+import {
+	BROWSER_PROTOCOL_TIMEOUT_MS,
+	canDecryptProfileCookies,
+	headlessExecutableForProfileReuse,
+	launchHeadlessBrowser,
+	loadPuppeteer,
+	type UserAgentOverride,
+} from "./launch";
 import { defaultDiscoveryEnv } from "./profile-discovery";
 import type { ProfileReusePosture } from "./profile-posture";
 import { resolveProfileReuse } from "./profile-reuse";
@@ -55,6 +63,17 @@ type SpawnedChromeProfileKind = Extract<BrowserKind, { kind: "chrome-profile" }>
 const browsers = new Map<string, BrowserHandle>();
 const browserOpenPromises = new Map<string, Promise<BrowserHandle>>();
 
+/**
+ * Chrome profile warm-up dirs this module created, keyed by the handle that owns one.
+ *
+ * Ownership is a registry-internal fact, not a property of the handle: `BrowserHandle`
+ * is exported and mutable, so a field would let any caller point recursive deletion at
+ * an arbitrary path. Recording the dir here — only on the launch path that created it —
+ * means disposal can delete exactly what this module made and nothing else. A path
+ * prefix check would not prove ownership; an entry in this map does.
+ */
+const ownedWarmupDirs = new WeakMap<BrowserHandle, string>();
+
 /**
  * Upper bound on the CDP `browser.close()` round-trip during a forced (signal-path)
  * teardown before we fall back to killing the Chrome process tree. Only applies when
@@ -110,6 +129,19 @@ export function browserKeyForTest(
 	return browserKey(kind, geo, opts.profileReuse);
 }
 
+/**
+ * Create and register a warm-up dir as registry-owned for `handle`.
+ *
+ * Exists so tests can exercise disposal without spawning Chrome. The caller cannot
+ * supply the deletion target: this module creates the directory itself before recording
+ * ownership, preserving the same invariant as the production launch path.
+ */
+export function createOwnedWarmupDirForTest(handle: BrowserHandle): string {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "gjc-profile-warmup-"));
+	ownedWarmupDirs.set(handle, dir);
+	return dir;
+}
+
 export async function acquireBrowser(kind: BrowserKind, opts: AcquireBrowserOptions): Promise<BrowserHandle> {
 	const geo = kind.kind === "headless" ? normalizeGeo(opts.geo) : undefined;
 	const key = browserKey(kind, geo, opts.profileReuse);
@@ -148,17 +180,38 @@ async function openBrowserHandle(
 				discoveryEnv: defaultDiscoveryEnv(fs.existsSync),
 			});
 			if (reuse.warning) logger.warn(reuse.warning);
-			if (reuse.mode === "real" && reuse.warmupDir) {
+			if (reuse.mode === "real" && reuse.warmupDir && reuse.discovered) {
+				const executablePath = headlessExecutableForProfileReuse();
+				if (!canDecryptProfileCookies(executablePath, reuse.discovered.userDataDir)) {
+					try {
+						fs.rmSync(reuse.warmupDir, { recursive: true, force: true });
+					} catch {}
+					const hint = executablePath
+						? `Real Chrome profile at ${reuse.discovered.userDataDir} cannot be decrypted by ${executablePath} on macOS (Chrome Safe Storage vs Chromium Safe Storage Keychain mismatch). Using synthetic browser state instead. Set PUPPETEER_EXECUTABLE_PATH to the matching Chrome/Chromium binary.`
+						: `Real Chrome profile at ${reuse.discovered.userDataDir} found but no compatible browser executable is available on macOS (bundled Chromium cannot decrypt Chrome's cookies — Chrome Safe Storage vs Chromium Safe Storage). Using synthetic browser state instead. Set PUPPETEER_EXECUTABLE_PATH to /Applications/Google Chrome.app/Contents/MacOS/Google Chrome or install Chrome.`;
+					logger.warn(hint);
+				} else {
+					profileWarmupDir = reuse.warmupDir;
+				}
+			} else if (reuse.mode === "real" && reuse.warmupDir) {
 				profileWarmupDir = reuse.warmupDir;
 			}
 		}
-		const browser = await launchHeadlessBrowser({
-			headless: kind.headless,
-			viewport: opts.viewport,
-			profileWarmupDir,
-			...(geo ? { geo } : {}),
-		});
-		return {
+		let browser: Browser;
+		try {
+			browser = await launchHeadlessBrowser({
+				headless: kind.headless,
+				viewport: opts.viewport,
+				profileWarmupDir,
+				...(geo ? { geo } : {}),
+			});
+		} catch (error) {
+			// Launch failed after the warm-up copy landed: drop the temp dir here,
+			// because no handle will exist to carry it into releaseBrowser().
+			removeWarmupDir(profileWarmupDir);
+			throw error;
+		}
+		const handle: BrowserHandle = {
 			key,
 
 			kind,
@@ -168,6 +221,11 @@ async function openBrowserHandle(
 			refCount: 0,
 			stealth: { browserSession: null, override: null },
 		};
+		// Record ownership only here, where this module created the dir. Disposal
+		// deletes solely what this map holds, so a caller-supplied path is never
+		// a deletion target.
+		if (profileWarmupDir) ownedWarmupDirs.set(handle, profileWarmupDir);
+		return handle;
 	}
 	if (kind.kind === "connected") {
 		const cdpUrl = kind.cdpUrl.replace(/\/+$/, "");
@@ -418,6 +476,35 @@ export async function releaseBrowser(handle: BrowserHandle, opts: { kill: boolea
 	}
 }
 
+/**
+ * Delete the warm-up dir this module created for `handle`, if any.
+ *
+ * The path comes from `ownedWarmupDirs`, never from the caller, so recursive deletion
+ * can only ever target a dir this registry made. The entry is consumed first, making a
+ * second call a no-op even if disposal runs twice.
+ *
+ * Best-effort: a leftover temp dir is preferable to a teardown that throws.
+ */
+function removeOwnedWarmupDir(handle: BrowserHandle): void {
+	const dir = ownedWarmupDirs.get(handle);
+	if (dir === undefined) return;
+	ownedWarmupDirs.delete(handle);
+	removeWarmupDir(dir);
+}
+
+/** Delete a dir this module created. Callers must have proven ownership first. */
+function removeWarmupDir(dir: string | undefined): void {
+	if (!dir) return;
+	try {
+		fs.rmSync(dir, { recursive: true, force: true });
+	} catch (err) {
+		logger.debug("Failed to remove Chrome profile warm-up dir", {
+			dir,
+			error: (err as Error).message,
+		});
+	}
+}
+
 async function disposeBrowserHandle(handle: BrowserHandle, opts: { kill: boolean }): Promise<void> {
 	if (handle.kind.kind === "headless") {
 		// Capture the launched Chrome process before close() so a forced (signal-path)
@@ -436,6 +523,9 @@ async function disposeBrowserHandle(handle: BrowserHandle, opts: { kill: boolean
 			}
 		}
 		if (opts.kill && proc?.pid !== undefined) await gracefulKillTreeOnce(proc.pid);
+		// Chrome owns files under the warm-up dir until the process is gone, so this
+		// runs after close()/kill rather than alongside them.
+		removeOwnedWarmupDir(handle);
 		return;
 	}
 	if (handle.kind.kind === "connected") {

package/src/tools/cron.ts

@@ -453,13 +453,15 @@ function deliverCronFire(record: CronScheduleRecord): Promise<void> | undefined
 		cron_expression: record.snapshot.cron_expression,
 		recurring: record.snapshot.recurring,
 	};
-	const sendPromise = record.session.sendCustomMessage?.(
+	if (!record.session.sendCustomMessage) {
+		// The custom-message router is the only delivery path; treating its absence
+		// as a successful fire would silently retire a one-shot schedule.
+		return Promise.reject(new Error("Cron delivery requires a session custom-message router."));
+	}
+	return record.session.sendCustomMessage(
 		{ customType: "cron-fire", content, display: false, attribution: "agent", details },
 		{ triggerTurn: true, deliverAs: "followUp" },
 	);
-	if (sendPromise) return sendPromise;
-	record.session.steer?.({ customType: "cron-fire", content, details });
-	return undefined;
 }
 
 function scheduleRecord(ownerId: string | undefined, state: OwnerScheduleState, record: CronScheduleRecord): void {

package/src/tools/descriptors.test.ts

@@ -39,6 +39,7 @@ function makeSession(overrides: Record<string, unknown> = {}): any {
 		"calc.enabled": true,
 		"skill.enabled": true,
 		"browser.enabled": true,
+		"browser.backend": "native",
 		"computer.enabled": true,
 		"checkpoint.enabled": true,
 		"irc.enabled": true,
@@ -371,6 +372,20 @@ describe("tool descriptor compatibility gate", () => {
 		}
 	});
 
+	test("hides the built-in browser tool when Aside is the selected backend", () => {
+		const context = availabilityContext();
+
+		expect(BUILTIN_TOOL_DESCRIPTORS.browser.isAvailable(makeSession({ "browser.backend": "aside" }), context)).toBe(
+			false,
+		);
+		expect(BUILTIN_TOOL_DESCRIPTORS.browser.isAvailable(makeSession({ "browser.backend": "native" }), context)).toBe(
+			true,
+		);
+		expect(BUILTIN_TOOL_DESCRIPTORS.browser.isAvailable(makeSession({ "browser.backend": undefined }), context)).toBe(
+			true,
+		);
+	});
+
 	test("descriptor creation is side-effect free; materialization registers cleanup exactly once", () => {
 		const cleanupCalls: Array<() => void> = [];
 		let constructed = 0;

package/src/tools/descriptors.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@gajae-code/agent-core";
 import type { RawArgumentValidationResult, TSchema } from "@gajae-code/ai/types";
 import { $which } from "@gajae-code/utils";
+import { resolveBrowserBackend } from "../browser-backend";
 import type { ToolFactory, ToolSession } from ".";
 import { selectAskParameters } from "./ask-contract";
 import { isComputerCallable, isComputerLoadablePlatform } from "./computer-policy";
@@ -260,7 +261,10 @@ function availableFor(name: string, session: ToolSession, context = defaultAvail
 	if (name === "search_tool_bm25") return context.discoveryActive ?? resolveDiscoveryActive(session);
 	if (name === "calc") return Boolean(session.settings.get("calc.enabled"));
 	if (name === "skill" || name === "skill_discovery") return Boolean(session.settings.get("skill.enabled"));
-	if (name === "browser") return Boolean(session.settings.get("browser.enabled"));
+	if (name === "browser")
+		return (
+			Boolean(session.settings.get("browser.enabled")) && resolveBrowserBackend(session.settings).exposesBuiltinTool
+		);
 	if (name === "computer") return isComputerCallable(session);
 	if (name === "checkpoint" || name === "rewind")
 		return Boolean(session.settings.get("checkpoint.enabled")) && (session.taskDepth ?? 0) === 0;