@gajae-code/coding-agent 0.10.2 → 0.11.0

package/src/tools/browser/benchmark/detector-report.ts

@@ -0,0 +1,157 @@
+/**
+ * Offline stealth-detector benchmark model.
+ *
+ * Pure, deterministic logic for the anti-detection benchmark suite: it converts
+ * a browser-collected fingerprint probe into a normalized per-detector verdict,
+ * implements the falsifiable CI gate (see plan Phase 1 / R-T3), and renders a
+ * before/after report. No browser or network access lives here so it can be
+ * unit-tested deterministically; the harness that drives the real browser tool
+ * against vendored detector fixtures feeds its output into these functions.
+ */
+
+export type SignalStatus = "pass" | "fail";
+
+/** A single boolean fingerprint signal, e.g. "navigator.webdriver is undefined". */
+export interface DetectorSignal {
+	/** Stable identifier, used to diff across runs. */
+	id: string;
+	/** Human-readable label for the report. */
+	label: string;
+	/** `pass` means the signal looks human; `fail` means it leaks automation. */
+	status: SignalStatus;
+	/** Optional observed value for debugging. */
+	detail?: string;
+}
+
+export type AutomatedVerdict = "human" | "bot" | "unknown";
+
+/** Normalized result for one detector (e.g. bot.sannysoft, CreepJS). */
+export interface DetectorResult {
+	detector: string;
+	signals: DetectorSignal[];
+	/** Overall automated/not classification when the detector exposes one. */
+	automatedVerdict: AutomatedVerdict;
+	/** Absolute trust score (observability-only, never a hard gate). */
+	trustScore: number | null;
+}
+
+/** Shape emitted by the offline probe fixture on `window.__stealthProbe`. */
+export interface RawProbe {
+	detector: string;
+	signals: Array<{ id: string; label: string; pass: boolean; detail?: string }>;
+	automatedVerdict?: AutomatedVerdict;
+	trustScore?: number | null;
+}
+
+/** Convert a raw browser-collected probe into a normalized {@link DetectorResult}. */
+export function parseProbe(raw: RawProbe): DetectorResult {
+	if (!raw || typeof raw.detector !== "string" || !Array.isArray(raw.signals)) {
+		throw new Error("invalid stealth probe payload");
+	}
+	const signals: DetectorSignal[] = raw.signals.map(s => ({
+		id: s.id,
+		label: s.label,
+		status: s.pass ? "pass" : "fail",
+		...(s.detail !== undefined ? { detail: s.detail } : {}),
+	}));
+	return {
+		detector: raw.detector,
+		signals,
+		automatedVerdict: raw.automatedVerdict ?? "unknown",
+		trustScore: raw.trustScore ?? null,
+	};
+}
+
+function passCount(result: DetectorResult): number {
+	return result.signals.filter(s => s.status === "pass").length;
+}
+
+function failingSignalIds(result: DetectorResult): Set<string> {
+	return new Set(result.signals.filter(s => s.status === "fail").map(s => s.id));
+}
+
+export interface GateOutcome {
+	pass: boolean;
+	reasons: string[];
+}
+
+/**
+ * Falsifiable CI gate (plan Phase 1 / R-T3, R-C1, R-C2):
+ *   (a) zero failing signals in the current run, AND
+ *       current pass-count >= baseline pass-count (no silent regression), AND
+ *   (b) either at least one signal that failed at baseline now passes,
+ *       OR the baseline was already all-green (empty-gap regression lock).
+ * The absolute `trustScore` is never consulted here; it is observability-only.
+ */
+export function evaluateGate(baseline: DetectorResult, current: DetectorResult): GateOutcome {
+	const reasons: string[] = [];
+	const currentFail = failingSignalIds(current);
+	if (currentFail.size > 0) {
+		reasons.push(
+			`${current.detector}: ${currentFail.size} signal(s) still leak automation: ${[...currentFail].join(", ")}`,
+		);
+	}
+
+	const baselinePass = passCount(baseline);
+	const currentPass = passCount(current);
+	if (currentPass < baselinePass) {
+		reasons.push(`${current.detector}: pass-count regressed (${currentPass} < baseline ${baselinePass})`);
+	}
+
+	const baselineFail = failingSignalIds(baseline);
+	const currentPassIds = new Set(current.signals.filter(s => s.status === "pass").map(s => s.id));
+	const newlyPassing = [...baselineFail].filter(id => currentPassIds.has(id));
+	const baselineAllGreen = baselineFail.size === 0;
+	if (!baselineAllGreen && newlyPassing.length === 0) {
+		reasons.push(`${current.detector}: no baseline-failing signal was fixed (improvement required)`);
+	}
+
+	return { pass: reasons.length === 0, reasons };
+}
+
+/** Aggregate gate across every detector; passes only when all detectors pass. */
+export function evaluateSuiteGate(
+	baseline: readonly DetectorResult[],
+	current: readonly DetectorResult[],
+): GateOutcome {
+	const reasons: string[] = [];
+	const currentByName = new Map(current.map(r => [r.detector, r]));
+	for (const base of baseline) {
+		const now = currentByName.get(base.detector);
+		if (!now) {
+			reasons.push(`${base.detector}: missing from current run`);
+			continue;
+		}
+		reasons.push(...evaluateGate(base, now).reasons);
+	}
+	return { pass: reasons.length === 0, reasons };
+}
+
+/** Render a deterministic before/after markdown report for one run. */
+export function renderReport(baseline: readonly DetectorResult[], current: readonly DetectorResult[]): string {
+	const lines: string[] = ["# Stealth Benchmark Report", ""];
+	const gate = evaluateSuiteGate(baseline, current);
+	lines.push(`Gate: ${gate.pass ? "PASS" : "FAIL"}`, "");
+	const currentByName = new Map(current.map(r => [r.detector, r]));
+	for (const base of baseline) {
+		const now = currentByName.get(base.detector);
+		lines.push(`## ${base.detector}`);
+		lines.push(
+			`- Automated verdict: ${base.automatedVerdict} -> ${now?.automatedVerdict ?? "n/a"}`,
+			`- Trust score (observability): ${base.trustScore ?? "n/a"} -> ${now?.trustScore ?? "n/a"}`,
+			`- Passing signals: ${passCount(base)} -> ${now ? passCount(now) : "n/a"} of ${base.signals.length}`,
+			"",
+			"| Signal | Baseline | Current |",
+			"|--------|----------|---------|",
+		);
+		for (const sig of base.signals) {
+			const nowSig = now?.signals.find(s => s.id === sig.id);
+			lines.push(`| ${sig.label} | ${sig.status} | ${nowSig?.status ?? "n/a"} |`);
+		}
+		lines.push("");
+	}
+	if (!gate.pass) {
+		lines.push("## Blocking reasons", ...gate.reasons.map(r => `- ${r}`), "");
+	}
+	return lines.join("\n");
+}

package/src/tools/browser/benchmark/run-suite.ts

@@ -0,0 +1,39 @@
+/**
+ * Offline stealth benchmark harness (plan Phase 1).
+ *
+ * Drives a puppeteer Page (already stealth-patched by the browser tool) against
+ * self-contained offline detector fixtures and collects normalized results. The
+ * navigation/evaluation is injected so this stays unit-testable without a real
+ * browser; the integration test wires a live puppeteer Page.
+ */
+
+import type { Page } from "puppeteer-core";
+import type { DetectorResult, RawProbe } from "./detector-report";
+import { parseProbe } from "./detector-report";
+
+/** Minimal surface of a puppeteer Page that the harness needs. */
+export type SuitePage = Pick<Page, "goto" | "evaluate">;
+
+export interface SuiteFixture {
+	/** file:// (or http://) URL of the offline detector fixture. */
+	url: string;
+}
+
+/** Read the probe the fixture placed on `window.__stealthProbe`. */
+function readProbe(): RawProbe {
+	// Runs in the browser context.
+	const probe = (globalThis as unknown as { __stealthProbe?: RawProbe }).__stealthProbe;
+	if (!probe) throw new Error("fixture did not expose window.__stealthProbe");
+	return probe;
+}
+
+/** Navigate to each fixture and collect a normalized DetectorResult per fixture. */
+export async function runOfflineSuite(page: SuitePage, fixtures: readonly SuiteFixture[]): Promise<DetectorResult[]> {
+	const results: DetectorResult[] = [];
+	for (const fixture of fixtures) {
+		await page.goto(fixture.url, { waitUntil: "load" });
+		const raw = await page.evaluate(readProbe);
+		results.push(parseProbe(raw));
+	}
+	return results;
+}

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" };
+}