@gajae-code/coding-agent 0.10.1 → 0.11.0

package/src/tools/browser/launch.ts

@@ -14,11 +14,12 @@ import stealthWebglScript from "../puppeteer/05_stealth_webgl.txt" with { type:
 import stealthScreenScript from "../puppeteer/06_stealth_screen.txt" with { type: "text" };
 import stealthFontsScript from "../puppeteer/07_stealth_fonts.txt" with { type: "text" };
 import stealthAudioScript from "../puppeteer/08_stealth_audio.txt" with { type: "text" };
-import stealthLocaleScript from "../puppeteer/09_stealth_locale.txt" with { type: "text" };
 import stealthPluginsScript from "../puppeteer/10_stealth_plugins.txt" with { type: "text" };
 import stealthHardwareScript from "../puppeteer/11_stealth_hardware.txt" with { type: "text" };
 import stealthCodecsScript from "../puppeteer/12_stealth_codecs.txt" with { type: "text" };
 import stealthWorkerScript from "../puppeteer/13_stealth_worker.txt" with { type: "text" };
+import stealthPermissionsScript from "../puppeteer/14_stealth_permissions.txt" with { type: "text" };
+import stealthWebrtcScript from "../puppeteer/15_stealth_webrtc.txt" with { type: "text" };
 import { ToolError } from "../tool-errors";
 
 export const DEFAULT_VIEWPORT = { width: 1365, height: 768, deviceScaleFactor: 1.25 };
@@ -35,7 +36,6 @@ const STEALTH_IGNORE_DEFAULT_ARGS = [
 	"--disable-default-apps",
 	"--disable-component-extensions-with-background-pages",
 ];
-const STEALTH_ACCEPT_LANGUAGE = "en-US,en";
 
 const USER_AGENT_TARGET_TIMEOUT_MS = 5_000;
 const USER_AGENT_TARGET_TYPES = new Set(["page", "webview", "background_page"]);
@@ -230,6 +230,22 @@ function resolveSystemChromium(): string | undefined {
 export interface LaunchHeadlessOptions {
 	headless: boolean;
 	viewport?: { width: number; height: number; deviceScaleFactor?: number };
+	/**
+	 * Optional isolated warm-up profile directory (see profile-reuse.ts). When
+	 * set, the headless browser launches against this isolated copy of the user's
+	 * real Chrome profile so sessions inherit real cookies/storage/cache for
+	 * stronger stealth. Callers resolve this via resolveProfileReuse and MUST
+	 * pass an isolated copy, never a live profile dir.
+	 */
+	profileWarmupDir?: string;
+	/**
+	 * Optional opt-in geo alignment (see settings browser.geo.*). When set, the
+	 * browser is launched with a matching timezone (TZ env) and/or UI language
+	 * (--lang) at the source. Default unset = strict no-op: the real environment
+	 * timezone/locale are preserved (never half-spoof). Only align these to a
+	 * coherent value (e.g. one matching a configured proxy egress).
+	 */
+	geo?: { timezone?: string; locale?: string };
 }
 
 export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<Browser> {
@@ -244,8 +260,16 @@ export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promis
 		"--no-sandbox",
 		"--disable-setuid-sandbox",
 		"--disable-blink-features=AutomationControlled",
+		// Suppress WebRTC leaking the real local/public IP via ICE candidates
+		// (a common bot tell). Keeps WebRTC functional over the default public
+		// interface only; 15_stealth_webrtc.txt adds a candidate-level guard.
+		"--force-webrtc-ip-handling-policy=default_public_interface_only",
 		`--window-size=${initialViewport.width},${initialViewport.height}`,
 	];
+	if (opts.profileWarmupDir) {
+		// Isolated copy only (caller guarantees). Never point this at a live profile.
+		launchArgs.push(`--user-data-dir=${opts.profileWarmupDir}`);
+	}
 	const proxy = process.env.PUPPETEER_PROXY;
 	if (proxy) {
 		launchArgs.push(`--proxy-server=${proxy}`);
@@ -256,15 +280,22 @@ export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promis
 			launchArgs.push("--proxy-bypass-list=<-loopback>");
 		}
 	}
+	// Opt-in geo alignment (default no-op). Locale via --lang at the source;
+	// timezone via the TZ env passed to the Chrome subprocess.
+	if (opts.geo?.locale) {
+		launchArgs.push(`--lang=${opts.geo.locale}`);
+	}
 	const ignoreCert = process.env.PUPPETEER_PROXY_IGNORE_CERT_ERRORS?.toLowerCase();
 	if (ignoreCert === "true" || ignoreCert === "1" || ignoreCert === "yes" || ignoreCert === "on") {
 		launchArgs.push("--ignore-certificate-errors");
 	}
+	const launchEnv = opts.geo?.timezone ? { ...process.env, TZ: opts.geo.timezone } : undefined;
 	return await puppeteer.launch({
 		headless: opts.headless,
 		defaultViewport: opts.headless ? initialViewport : null,
 		executablePath: await ensureChromiumExecutable(),
 		args: launchArgs,
+		...(launchEnv ? { env: launchEnv } : {}),
 		ignoreDefaultArgs: [...STEALTH_IGNORE_DEFAULT_ARGS],
 		protocolTimeout: BROWSER_PROTOCOL_TIMEOUT_MS,
 	});
@@ -308,6 +339,20 @@ export interface UserAgentOverride {
 	};
 }
 
+function acceptLanguageForLocale(locale: string): string {
+	const canonicalLocale = Intl.getCanonicalLocales(locale)[0]!;
+	const baseLanguage = canonicalLocale.split("-")[0]!;
+	return canonicalLocale === baseLanguage ? canonicalLocale : `${canonicalLocale},${baseLanguage}`;
+}
+
+async function resolveAcceptLanguage(page: Page, locale?: string): Promise<string> {
+	if (locale) return acceptLanguageForLocale(locale);
+	const languages = await page.evaluate(() => [...navigator.languages]);
+	const acceptLanguage = languages.filter(Boolean).join(",");
+	if (!acceptLanguage) throw new ToolError("Chromium reported no native navigator languages");
+	return acceptLanguage;
+}
+
 function resolvePageClient(page: Page): PuppeteerCdpClient | null {
 	const pageWithClient = page as Page & {
 		_client?: (() => PuppeteerCdpClient) | PuppeteerCdpClient;
@@ -362,7 +407,7 @@ function patchSourceUrl(page: Page): void {
 	};
 }
 
-async function resolveUserAgentOverride(page: Page): Promise<UserAgentOverride> {
+async function resolveUserAgentOverride(page: Page, locale?: string): Promise<UserAgentOverride> {
 	const rawUserAgent = await page.browser().userAgent();
 	let userAgent = rawUserAgent.replace("HeadlessChrome/", "Chrome/");
 	if (userAgent.includes("Linux") && !userAgent.includes("Android")) {
@@ -413,11 +458,13 @@ async function resolveUserAgentOverride(page: Page): Promise<UserAgentOverride>
 	brands[order[0]!] = { brand: greaseyBrand, version: "99" };
 	brands[order[1]!] = { brand: "Chromium", version: String(majorVersion) };
 	brands[order[2]!] = { brand: "Google Chrome", version: String(majorVersion) };
+	const acceptLanguage = await resolveAcceptLanguage(page, locale);
 
 	return {
 		userAgent,
 		platform,
-		acceptLanguage: STEALTH_ACCEPT_LANGUAGE,
+		acceptLanguage,
+
 		userAgentMetadata: {
 			brands,
 			fullVersion: uaVersion,
@@ -436,7 +483,17 @@ function wrapSession(session: CDPSession): PuppeteerCdpClient {
 	};
 }
 
-async function sendUserAgentOverride(client: PuppeteerCdpClient, override: UserAgentOverride): Promise<void> {
+async function sendUserAgentOverride(
+	client: PuppeteerCdpClient,
+	override: UserAgentOverride,
+	strict = false,
+): Promise<void> {
+	if (strict) {
+		await client.send("Network.enable");
+		await client.send("Network.setUserAgentOverride", override as unknown as Record<string, unknown>);
+		await client.send("Emulation.setUserAgentOverride", override as unknown as Record<string, unknown>);
+		return;
+	}
 	try {
 		await client.send("Network.enable");
 	} catch {}
@@ -464,28 +521,52 @@ export interface UserAgentSession {
 /** Configure UA override on the browser + auto-attach to new targets. */
 async function configureUserAgentTargets(
 	browser: Browser,
-	state: { browserSession: CDPSession | null; override: UserAgentOverride },
+	state: { browserSession: CDPSession | null; override: UserAgentOverride; locale?: string },
+
 	targetTimeoutMs = USER_AGENT_TARGET_TIMEOUT_MS,
 ): Promise<void> {
 	if (!state.browserSession) {
 		state.browserSession = await browser.target().createCDPSession();
 		await state.browserSession.send("Target.setAutoAttach", {
 			autoAttach: true,
-			waitForDebuggerOnStart: false,
+			waitForDebuggerOnStart: true,
 			flatten: true,
 		});
 		state.browserSession.on(
 			"Target.attachedToTarget",
-			async (event: { sessionId: string; targetInfo?: { type?: string } }) => {
-				if (!targetInfoSupportsUserAgentOverride(event.targetInfo)) return;
+			async (event: { sessionId: string; targetInfo?: { targetId?: string; type?: string } }) => {
+				if (!targetInfoSupportsUserAgentOverride(event.targetInfo)) {
+					const connection = state.browserSession?.connection();
+					await connection
+						?.session(event.sessionId)
+						?.send("Runtime.runIfWaitingForDebugger")
+						.catch(() => undefined);
+					return;
+				}
 				const connection = state.browserSession?.connection();
 				const session = connection?.session(event.sessionId);
 				if (!session) return;
-				await withSoftTimeout(
-					sendUserAgentOverride(wrapSession(session), state.override),
-					targetTimeoutMs,
-					"new target user-agent override",
-				);
+				try {
+					if (state.locale) {
+						await applyClientOverrides(wrapSession(session), state.override, state.locale, true);
+					} else {
+						await withSoftTimeout(
+							sendUserAgentOverride(wrapSession(session), state.override),
+							targetTimeoutMs,
+							"new target user-agent override",
+						);
+					}
+					await session.send("Runtime.runIfWaitingForDebugger");
+				} catch (error) {
+					if (event.targetInfo?.targetId) {
+						await state.browserSession
+							?.send("Target.closeTarget", { targetId: event.targetInfo.targetId })
+							.catch(() => undefined);
+					}
+					logger.debug("Closed target after geo override failure", {
+						error: error instanceof Error ? error.message : String(error),
+					});
+				}
 			},
 		);
 	}
@@ -511,14 +592,33 @@ function targetInfoSupportsUserAgentOverride(targetInfo: { type?: string } | und
 }
 
 async function applyTargetUserAgentOverride(target: Target, override: UserAgentOverride): Promise<void> {
+	await applyTargetOverrides(target, override);
+}
+
+async function applyTargetOverrides(
+	target: Target,
+	override: UserAgentOverride,
+	locale?: string,
+	strict = false,
+): Promise<void> {
 	const session = await target.createCDPSession();
 	try {
-		await sendUserAgentOverride(wrapSession(session), override);
+		await applyClientOverrides(wrapSession(session), override, locale, strict);
 	} finally {
 		await session.detach().catch(() => undefined);
 	}
 }
 
+async function applyClientOverrides(
+	client: PuppeteerCdpClient,
+	override: UserAgentOverride,
+	locale?: string,
+	strict = false,
+): Promise<void> {
+	await sendUserAgentOverride(client, override, strict);
+	if (locale) await client.send("Emulation.setLocaleOverride", { locale });
+}
+
 async function withSoftTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T | undefined> {
 	let timeout: NodeJS.Timeout | undefined;
 	const timeoutPromise = new Promise<undefined>(resolve => {
@@ -550,11 +650,12 @@ const STEALTH_PATCH_SCRIPTS = [
 	stealthScreenScript,
 	stealthFontsScript,
 	stealthAudioScript,
-	stealthLocaleScript,
 	stealthPluginsScript,
 	stealthHardwareScript,
 	stealthCodecsScript,
 	stealthWorkerScript,
+	stealthPermissionsScript,
+	stealthWebrtcScript,
 ];
 
 function buildStealthInjectionScript(scripts: readonly string[] = STEALTH_PATCH_SCRIPTS): string {
@@ -624,17 +725,21 @@ export async function applyStealthPatches(
 	browser: Browser,
 	page: Page,
 	state: { browserSession: CDPSession | null; override: UserAgentOverride | null },
+	geo?: { readonly timezone?: string; readonly locale?: string },
 ): Promise<void> {
 	patchSourceUrl(page);
 	if (!state.override) {
-		state.override = await resolveUserAgentOverride(page);
+		state.override = await resolveUserAgentOverride(page, geo?.locale);
 	}
 	const client = resolvePageClient(page);
 	if (client) {
-		await sendUserAgentOverride(client, state.override);
+		await sendUserAgentOverride(client, state.override, Boolean(geo?.locale));
 	}
-	const targetState = { browserSession: state.browserSession, override: state.override };
+	const targetState = { browserSession: state.browserSession, override: state.override, locale: geo?.locale };
 	await configureUserAgentTargets(browser, targetState);
+	if (client && geo?.locale) {
+		await client.send("Emulation.setLocaleOverride", { locale: geo.locale });
+	}
 	state.browserSession = targetState.browserSession;
 	await injectStealthScripts(page);
 }

package/src/tools/browser/profile-discovery.ts

@@ -0,0 +1,63 @@
+/**
+ * Default Chrome profile discovery (plan Phase 2 wiring).
+ *
+ * Locates the user's real Chrome "Default" profile directory per OS so the
+ * default headless launch path can warm up synthetic sessions from an isolated
+ * copy of it (see profile-warmup.ts + profile-posture.ts). Pure path logic with
+ * an injectable existence check, so it is unit-testable without touching the
+ * real filesystem.
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface DiscoveryEnv {
+	platform: NodeJS.Platform;
+	home: string;
+	/** Injectable for tests; defaults to fs.existsSync at call sites. */
+	exists: (p: string) => boolean;
+	/** Windows LOCALAPPDATA override (tests / non-default installs). */
+	localAppData?: string;
+}
+
+/** Candidate Chrome user-data roots for the platform (most common first). */
+export function chromeUserDataRoots(env: DiscoveryEnv): string[] {
+	switch (env.platform) {
+		case "darwin":
+			return [path.join(env.home, "Library", "Application Support", "Google", "Chrome")];
+		case "win32": {
+			const localAppData = env.localAppData ?? path.join(env.home, "AppData", "Local");
+			return [path.join(localAppData, "Google", "Chrome", "User Data")];
+		}
+		default:
+			return [path.join(env.home, ".config", "google-chrome"), path.join(env.home, ".config", "chromium")];
+	}
+}
+
+export interface DiscoveredProfile {
+	userDataDir: string;
+	profileDirectory: string;
+	profileDir: string;
+}
+
+/**
+ * Discover the default Chrome profile, or null when none is present.
+ * Only returns a profile whose directory actually exists.
+ */
+export function discoverDefaultChromeProfile(
+	env: DiscoveryEnv,
+	profileDirectory = "Default",
+): DiscoveredProfile | null {
+	for (const userDataDir of chromeUserDataRoots(env)) {
+		const profileDir = path.join(userDataDir, profileDirectory);
+		if (env.exists(profileDir)) {
+			return { userDataDir, profileDirectory, profileDir };
+		}
+	}
+	return null;
+}
+
+/** Convenience wrapper using the live OS environment + fs. */
+export function defaultDiscoveryEnv(exists: (p: string) => boolean): DiscoveryEnv {
+	return { platform: process.platform, home: os.homedir(), exists };
+}

package/src/tools/browser/profile-posture.ts

@@ -0,0 +1,59 @@
+/**
+ * Auto-default profile-reuse posture decision (plan Phase 2, Intent Reconciliation).
+ *
+ * User-confirmed policy: when a usable real Chrome profile is available, the
+ * browser tool uses it automatically (AUTO), emits a warning, and falls back to
+ * synthetic stealth when unavailable. The posture is overridable via a setting.
+ * This is pure decision logic (no browser, no filesystem side effects) so the
+ * launch/attach layer can call it and it can be unit-tested deterministically.
+ */
+
+/** Configured posture: `auto` (default) prefers the real profile; `opt-in` stays synthetic unless explicitly asked. */
+export type ProfileReusePosture = "auto" | "opt-in";
+
+export const DEFAULT_PROFILE_REUSE_POSTURE: ProfileReusePosture = "auto";
+
+export interface PostureInputs {
+	/** Configured posture; defaults to `auto` when unset. */
+	posture?: ProfileReusePosture;
+	/** A usable real Chrome profile was detected and is attachable/safe to copy. */
+	realProfileAvailable: boolean;
+	/** Caller explicitly requested real-profile reuse for this run (e.g. app.browser === "chrome"). */
+	explicitlyRequested?: boolean;
+}
+
+export interface PostureDecision {
+	/** `real` = use the (isolated copy of the) real profile; `synthetic` = synthetic stealth session. */
+	mode: "real" | "synthetic";
+	/** User-facing warning to emit when real credentials/state are about to be used. */
+	warning: string | null;
+	/** Machine-readable reason for logs/audit. */
+	reason: "auto-real" | "explicit-real" | "synthetic-fallback" | "synthetic-opt-in";
+}
+
+/**
+ * Decide whether to reuse the real profile or run synthetic.
+ *
+ * - `auto` + available            -> real (with warning)
+ * - `opt-in` + explicitly asked   -> real (with warning)
+ * - `opt-in` (no explicit ask)    -> synthetic
+ * - not available                 -> synthetic (fallback), even under `auto`
+ */
+export function decideProfilePosture(inputs: PostureInputs): PostureDecision {
+	const posture = inputs.posture ?? DEFAULT_PROFILE_REUSE_POSTURE;
+	const warning =
+		"Using an isolated copy of your real Chrome profile (cookies/session/cache) for stealth. " +
+		"Real logged-in credentials may be exercised on visited pages. Set browser.profileReuse to 'opt-in' to disable.";
+
+	if (!inputs.realProfileAvailable) {
+		return { mode: "synthetic", warning: null, reason: "synthetic-fallback" };
+	}
+	if (posture === "auto") {
+		return { mode: "real", warning, reason: "auto-real" };
+	}
+	// opt-in
+	if (inputs.explicitlyRequested) {
+		return { mode: "real", warning, reason: "explicit-real" };
+	}
+	return { mode: "synthetic", warning: null, reason: "synthetic-opt-in" };
+}

package/src/tools/browser/profile-reuse.ts

@@ -0,0 +1,102 @@
+/**
+ * Profile-reuse orchestration (plan Phase 2 wiring).
+ *
+ * Single entry point the launch path calls to decide, for a default headless
+ * session, whether to warm up from an isolated copy of the user's real Chrome
+ * profile. Ties together discovery + posture + isolated warm-up. Filesystem
+ * effects (the copy) are performed only when the posture resolves to `real`.
+ * The heavy pieces are injectable so this is unit-testable without a browser.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { type DiscoveredProfile, type DiscoveryEnv, discoverDefaultChromeProfile } from "./profile-discovery";
+import { decideProfilePosture, type ProfileReusePosture } from "./profile-posture";
+import { collectWarmupArtifacts, type WarmupManifest } from "./profile-warmup";
+
+export interface ResolveProfileReuseInputs {
+	posture?: ProfileReusePosture;
+	/** Caller explicitly requested real-profile reuse (e.g. app.browser === "chrome"). */
+	explicitlyRequested?: boolean;
+	discoveryEnv: DiscoveryEnv;
+	/** Destination for the isolated warm-up copy; defaults to an ephemeral temp dir. */
+	destDir?: string;
+	/** Injectable copier (defaults to collectWarmupArtifacts). */
+	copy?: (sourceProfileDir: string, destDir: string) => WarmupManifest;
+	/** Injectable temp-dir factory (defaults to fs.mkdtemp under os.tmpdir()). */
+	makeTempDir?: () => string;
+}
+
+export interface ProfileReuseResult {
+	mode: "real" | "synthetic";
+	reason: string;
+	warning: string | null;
+	discovered: DiscoveredProfile | null;
+	/** Isolated copy directory when mode === "real", else null. */
+	warmupDir: string | null;
+	manifest: WarmupManifest | null;
+}
+
+function defaultTempDir(): string {
+	return fs.mkdtempSync(path.join(os.tmpdir(), "gjc-profile-warmup-"));
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Resolve profile reuse for a default session. When the posture resolves to
+ * `real`, copies an allowlisted, lock-free subset of the discovered profile
+ * into an isolated dir and returns that dir for the launcher to use.
+ */
+export function resolveProfileReuse(inputs: ResolveProfileReuseInputs): ProfileReuseResult {
+	const discovered = discoverDefaultChromeProfile(inputs.discoveryEnv);
+	const decision = decideProfilePosture({
+		posture: inputs.posture,
+		realProfileAvailable: discovered !== null,
+		explicitlyRequested: inputs.explicitlyRequested,
+	});
+
+	if (decision.mode !== "real" || !discovered) {
+		return {
+			mode: "synthetic",
+			reason: decision.reason,
+			warning: null,
+			discovered,
+			warmupDir: null,
+			manifest: null,
+		};
+	}
+
+	const ownsDestDir = inputs.destDir === undefined;
+	let destDir: string | undefined;
+	const copy = inputs.copy ?? collectWarmupArtifacts;
+	try {
+		destDir = inputs.destDir ?? (inputs.makeTempDir ?? defaultTempDir)();
+		const manifest = copy(discovered.profileDir, destDir);
+		return {
+			mode: "real",
+			reason: decision.reason,
+			warning: decision.warning,
+			discovered,
+			warmupDir: destDir,
+			manifest,
+		};
+	} catch (error) {
+		if (ownsDestDir && destDir) {
+			try {
+				fs.rmSync(destDir, { recursive: true, force: true });
+			} catch {}
+		}
+		return {
+			mode: "synthetic",
+			reason: "synthetic-copy-failed",
+			warning: `Could not safely copy the discovered Chrome profile; using synthetic browser state instead: ${errorMessage(error)}`,
+			discovered,
+			warmupDir: null,
+			manifest: null,
+		};
+	}
+}

package/src/tools/browser/profile-warmup.ts

@@ -0,0 +1,109 @@
+/**
+ * Isolated profile warm-up (plan Phase 2, R-C3).
+ *
+ * Aggressive real-profile reuse seeds a session with the user's cookies /
+ * localStorage / cache. To stay safe (never lock or corrupt the live browser
+ * session) we NEVER bind the source profile directly: we copy an allowlisted
+ * subset of artifacts into an ephemeral, isolated directory and drive Chromium
+ * against that copy. Chromium single-instance lock files (SingletonLock/Socket/
+ * Cookie) are explicitly excluded so the isolated copy can never contend with a
+ * running browser.
+ *
+ * This module is pure filesystem logic (no browser, no network) so it is
+ * deterministically unit-testable.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Chromium single-instance lock artifacts — must never be copied. */
+export const CHROME_LOCK_ARTIFACTS = ["SingletonLock", "SingletonSocket", "SingletonCookie"] as const;
+const CHROME_LOCK_ARTIFACT_SET = new Set<string>(CHROME_LOCK_ARTIFACTS);
+
+/**
+ * Profile-relative artifacts worth seeding for warm-up. Kept intentionally
+ * small: session state (cookies, storage) plus a light cache. Anything not
+ * listed is skipped, which also keeps the isolated copy cheap.
+ */
+export const WARMUP_ARTIFACTS = [
+	"Cookies",
+	"Cookies-journal",
+	"Local Storage",
+	"Session Storage",
+	"IndexedDB",
+	"Network",
+	"Preferences",
+] as const;
+
+export interface WarmupManifest {
+	sourceProfileDir: string;
+	destDir: string;
+	copied: string[];
+	skippedMissing: string[];
+	/** Always empty unless a lock artifact was seen (never copied). */
+	excludedLocks: string[];
+}
+
+function copyRecursive(src: string, dest: string, manifest: WarmupManifest): void {
+	const stat = fs.statSync(src);
+	if (stat.isDirectory()) {
+		fs.mkdirSync(dest, { recursive: true });
+		for (const entry of fs.readdirSync(src)) {
+			if (CHROME_LOCK_ARTIFACT_SET.has(entry)) {
+				if (!manifest.excludedLocks.includes(entry)) manifest.excludedLocks.push(entry);
+				continue;
+			}
+			copyRecursive(path.join(src, entry), path.join(dest, entry), manifest);
+		}
+	} else {
+		fs.mkdirSync(path.dirname(dest), { recursive: true });
+		fs.copyFileSync(src, dest);
+	}
+}
+
+/**
+ * Copy warm-up artifacts from `sourceProfileDir` into an isolated `destDir`.
+ *
+ * Guarantees:
+ * - The source profile is only ever read, never written or locked.
+ * - Chromium lock artifacts are never copied (recorded in `excludedLocks`).
+ * - Missing artifacts are skipped, not fatal (recorded in `skippedMissing`).
+ */
+export function collectWarmupArtifacts(sourceProfileDir: string, destDir: string): WarmupManifest {
+	const manifest: WarmupManifest = {
+		sourceProfileDir,
+		destDir,
+		copied: [],
+		skippedMissing: [],
+		excludedLocks: [],
+	};
+
+	if (!fs.existsSync(sourceProfileDir)) {
+		throw new Error(`source profile directory does not exist: ${sourceProfileDir}`);
+	}
+	const resolvedSource = path.resolve(sourceProfileDir);
+	const resolvedDest = path.resolve(destDir);
+	if (resolvedDest === resolvedSource || resolvedDest.startsWith(`${resolvedSource}${path.sep}`)) {
+		throw new Error("warm-up destination must be outside the source profile directory");
+	}
+	fs.mkdirSync(destDir, { recursive: true });
+
+	// Record (but never copy) any lock artifacts present in the source.
+	for (const lock of CHROME_LOCK_ARTIFACTS) {
+		if (fs.existsSync(path.join(sourceProfileDir, lock))) {
+			manifest.excludedLocks.push(lock);
+		}
+	}
+
+	for (const artifact of WARMUP_ARTIFACTS) {
+		const src = path.join(sourceProfileDir, artifact);
+		if (!fs.existsSync(src)) {
+			manifest.skippedMissing.push(artifact);
+			continue;
+		}
+		copyRecursive(src, path.join(destDir, artifact), manifest);
+		manifest.copied.push(artifact);
+	}
+
+	return manifest;
+}