pi-agent-browser-native 0.2.40 → 0.2.41

package/extensions/agent-browser/lib/config.ts

@@ -1,217 +1,97 @@
 /**
  * Purpose: Load pi-agent-browser-native package configuration from Pi-scoped global, project, or explicit paths.
- * Responsibilities: Resolve config paths, validate the v1 JSON shape, merge layers, classify credential sources, resolve secrets without exposing values, and provide redacted status for tools/CLIs.
- * Scope: Package-owned configuration only; browser command execution and web-search API calls live in focused modules.
- * Usage: The extension reads this at startup to decide optional tool registration; scripts/config.mjs mirrors the file locations for user setup.
- * Invariants/Assumptions: Raw project-local plaintext credentials are unsafe and rejected; command credentials are resolved lazily at execution time.
+ * Responsibilities: Resolve config layers, resolve secrets without exposing values, and provide redacted status for tools/CLIs.
+ * Scope: Package-owned configuration only; canonical config policy lives in config-policy.js, browser command execution and web-search API calls live in focused modules.
+ * Invariants/Assumptions: Raw project-local plaintext credentials are unsafe and rejected by the shared config policy; command credentials are resolved lazily at execution time.
  */
 
 import { exec as execCallback } from "node:child_process";
-import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 
-const exec = promisify(execCallback);
-
-export const AGENT_BROWSER_CONFIG_ENV = "PI_AGENT_BROWSER_CONFIG";
-export const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
-export const CONFIG_RELATIVE_PATH = [".pi", "config", "pi-agent-browser-native", "config.json"] as const;
-export const GLOBAL_CONFIG_RELATIVE_PATH = [".pi", "config", "pi-agent-browser-native", "config.json"] as const;
-export const SECRET_COMMAND_TIMEOUT_MS = 15_000;
-
-export type BrowserDefaultProfilePolicy = "explicit-only" | "authenticated-only" | "always";
-export type AgentBrowserConfigScope = "global" | "project" | "override" | "env-fallback";
-export type CredentialSourceKind = "literal" | "env" | "command";
-
-export interface BrowserDefaultProfileConfig {
-	name: string;
-	policy?: BrowserDefaultProfilePolicy;
-}
-
-export interface AgentBrowserConfig {
-	version?: 1;
-	webSearch?: {
-		braveApiKey?: string;
-	};
-	browser?: {
-		defaultProfile?: BrowserDefaultProfileConfig;
-		defaultLaunchArgs?: string[];
-	};
-}
+import {
+	SECRET_COMMAND_TIMEOUT_MS,
+	buildAgentBrowserConfigState,
+	getAgentBrowserConfigPaths,
+	getWebSearchCredentialSource,
+	getWebSearchProviderOrder,
+	loadAgentBrowserConfigStateSync,
+	mergeAgentBrowserConfig,
+	parseAgentBrowserConfigLayer,
+	resolveEnvInterpolations,
+} from "./config-policy.js";
+import type {
+	AgentBrowserConfig,
+	AgentBrowserConfigScope,
+	AgentBrowserConfigState,
+	BrowserDefaultProfileConfig,
+	BrowserDefaultProfilePolicy,
+	ConfigLayer,
+	CredentialSource,
+	CredentialSourceKind,
+	WebSearchProvider,
+} from "./config-policy.js";
+
+export {
+	AGENT_BROWSER_CONFIG_ENV,
+	BRAVE_API_KEY_ENV,
+	CONFIG_RELATIVE_PATH,
+	DEFAULT_WEB_SEARCH_PROVIDER,
+	EXA_API_KEY_ENV,
+	GLOBAL_CONFIG_RELATIVE_PATH,
+	SECRET_COMMAND_TIMEOUT_MS,
+	WEB_SEARCH_PROVIDER_CONFIG_KEYS,
+	WEB_SEARCH_PROVIDER_DESCRIPTORS,
+	WEB_SEARCH_PROVIDER_ENV_VARS,
+	WEB_SEARCH_PROVIDERS,
+	buildAgentBrowserConfigState,
+	buildWebSearchCredentialSources,
+	canRegisterWebSearchTool,
+	classifyCredentialSource,
+	formatBrowserExecutableStatus,
+	formatBrowserProfileStatus,
+	getAgentBrowserConfigPaths,
+	getCredentialSourceSummary,
+	getGlobalAgentBrowserConfigPath,
+	getProjectAgentBrowserConfigPath,
+	getWebSearchCredentialSource,
+	getWebSearchProviderConfigKey,
+	getWebSearchProviderDescriptor,
+	getWebSearchProviderEnvVar,
+	getWebSearchProviderLabel,
+	getWebSearchProviderOrder,
+	hasPotentialCredentialSource,
+	isPlaintextCredentialValue,
+	isProjectSafeCredentialValueForProvider,
+	isWebSearchProvider,
+	loadAgentBrowserConfigStateSync,
+	mergeAgentBrowserConfig,
+	parseAgentBrowserConfigLayer,
+	resolveEnvInterpolations,
+	summarizeConfigFiles,
+	validateAgentBrowserConfig,
+	validateWebSearchProvider,
+} from "./config-policy.js";
+export type {
+	AgentBrowserConfig,
+	AgentBrowserConfigScope,
+	AgentBrowserConfigState,
+	BrowserDefaultProfileConfig,
+	BrowserDefaultProfilePolicy,
+	ConfigLayer,
+	CredentialSource,
+	CredentialSourceKind,
+	WebSearchProvider,
+	WebSearchProviderDescriptor,
+} from "./config-policy.js";
 
-export interface ConfigLayer {
-	config: AgentBrowserConfig;
-	path: string;
-	scope: Exclude<AgentBrowserConfigScope, "env-fallback">;
-}
-
-export interface CredentialSource {
-	kind: CredentialSourceKind;
-	rawValue: string;
-	scope: AgentBrowserConfigScope;
-}
-
-export interface AgentBrowserConfigState {
-	browserDefaultProfile?: Required<BrowserDefaultProfileConfig>;
-	config: AgentBrowserConfig;
-	credentialSource?: CredentialSource;
-	errors: string[];
-	layers: ConfigLayer[];
-	paths: {
-		global: string;
-		project: string;
-		override?: string;
-	};
-	warnings: string[];
-}
+const exec = promisify(execCallback);
 
 export interface ResolvedCredential {
 	source: CredentialSource;
 	value: string;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function hasOwn(value: Record<string, unknown>, key: string): boolean {
-	return Object.prototype.hasOwnProperty.call(value, key);
-}
-
-export function getGlobalAgentBrowserConfigPath(env: NodeJS.ProcessEnv = process.env): string {
-	const home = env.HOME?.trim() || env.USERPROFILE?.trim() || homedir();
-	return join(home, ...GLOBAL_CONFIG_RELATIVE_PATH);
-}
-
-export function getProjectAgentBrowserConfigPath(cwd = process.cwd()): string {
-	return resolve(cwd, ...CONFIG_RELATIVE_PATH);
-}
-
-export function getAgentBrowserConfigPaths(options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}) {
-	const env = options.env ?? process.env;
-	const override = env[AGENT_BROWSER_CONFIG_ENV]?.trim();
-	return {
-		global: getGlobalAgentBrowserConfigPath(env),
-		project: getProjectAgentBrowserConfigPath(options.cwd),
-		override: override ? resolve(override) : undefined,
-	};
-}
-
-function mergeConfig(base: AgentBrowserConfig, override: AgentBrowserConfig): AgentBrowserConfig {
-	return {
-		...base,
-		...override,
-		browser: {
-			...(base.browser ?? {}),
-			...(override.browser ?? {}),
-			defaultProfile: override.browser?.defaultProfile ?? base.browser?.defaultProfile,
-		},
-		webSearch: {
-			...(base.webSearch ?? {}),
-			...(override.webSearch ?? {}),
-		},
-	};
-}
-
-function validateString(value: unknown, path: string, errors: string[]): string | undefined {
-	if (value === undefined) return undefined;
-	if (typeof value !== "string") {
-		errors.push(`${path} must be a string.`);
-		return undefined;
-	}
-	return value;
-}
-
-function validateStringArray(value: unknown, path: string, errors: string[]): string[] | undefined {
-	if (value === undefined) return undefined;
-	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
-		errors.push(`${path} must be an array of strings.`);
-		return undefined;
-	}
-	return value;
-}
-
-function validateBrowserDefaultProfile(value: unknown, path: string, errors: string[]): BrowserDefaultProfileConfig | undefined {
-	if (value === undefined) return undefined;
-	if (!isRecord(value)) {
-		errors.push(`${path} must be an object.`);
-		return undefined;
-	}
-	const name = validateString(value.name, `${path}.name`, errors)?.trim();
-	if (!name) {
-		errors.push(`${path}.name must not be blank.`);
-		return undefined;
-	}
-	const rawPolicy = validateString(value.policy, `${path}.policy`, errors);
-	const policy = rawPolicy ?? "authenticated-only";
-	if (!(["explicit-only", "authenticated-only", "always"] as const).includes(policy as BrowserDefaultProfilePolicy)) {
-		errors.push(`${path}.policy must be one of explicit-only, authenticated-only, always.`);
-		return undefined;
-	}
-	return { name, policy: policy as BrowserDefaultProfilePolicy };
-}
-
-function validateConfig(value: unknown, path: string, scope: ConfigLayer["scope"], errors: string[], warnings: string[]): AgentBrowserConfig | undefined {
-	if (!isRecord(value)) {
-		errors.push(`${path} must contain a JSON object.`);
-		return undefined;
-	}
-	if (value.version !== undefined && value.version !== 1) {
-		errors.push(`${path}.version must be 1 when present.`);
-	}
-	const config: AgentBrowserConfig = value.version === 1 ? { version: 1 } : {};
-
-	if (value.webSearch !== undefined) {
-		if (!isRecord(value.webSearch)) {
-			errors.push(`${path}.webSearch must be an object.`);
-		} else {
-			const braveApiKey = validateString(value.webSearch.braveApiKey, `${path}.webSearch.braveApiKey`, errors);
-			if (braveApiKey !== undefined) {
-				config.webSearch = { braveApiKey };
-				if (scope === "project" && !isProjectSafeCredentialValue(braveApiKey)) {
-					errors.push(`${path}.webSearch.braveApiKey must be exactly $ENV_VAR or ${"${ENV_VAR}"} in project-local config; plaintext, interpolation literals, malformed env references, and command-backed project secrets are not allowed.`);
-				}
-			}
-		}
-	}
-
-	if (value.browser !== undefined) {
-		if (!isRecord(value.browser)) {
-			errors.push(`${path}.browser must be an object.`);
-		} else {
-			config.browser = {};
-			const defaultProfile = validateBrowserDefaultProfile(value.browser.defaultProfile, `${path}.browser.defaultProfile`, errors);
-			if (defaultProfile) config.browser.defaultProfile = defaultProfile;
-			const defaultLaunchArgs = validateStringArray(value.browser.defaultLaunchArgs, `${path}.browser.defaultLaunchArgs`, errors);
-			if (defaultLaunchArgs) {
-				config.browser.defaultLaunchArgs = defaultLaunchArgs;
-				warnings.push(`${path}.browser.defaultLaunchArgs is recorded for future use; current releases do not auto-inject default launch args.`);
-			}
-		}
-	}
-
-	for (const key of Object.keys(value)) {
-		if (!["version", "webSearch", "browser"].includes(key)) {
-			warnings.push(`${path}.${key} is not a recognized pi-agent-browser-native config field and was ignored.`);
-		}
-	}
-	return config;
-}
-
-function parseConfigLayer(raw: string, path: string, scope: ConfigLayer["scope"], errors: string[], warnings: string[]): ConfigLayer | undefined {
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (error) {
-		errors.push(`Could not parse ${scope} config ${path}: ${error instanceof Error ? error.message : String(error)}`);
-		return undefined;
-	}
-	const config = validateConfig(parsed, path, scope, errors, warnings);
-	return config ? { config, path, scope } : undefined;
-}
-
 async function readConfigLayer(path: string, scope: ConfigLayer["scope"], errors: string[], warnings: string[]): Promise<ConfigLayer | undefined> {
 	let raw: string;
 	try {
@@ -223,78 +103,7 @@ async function readConfigLayer(path: string, scope: ConfigLayer["scope"], errors
 		errors.push(`Could not read ${scope} config ${path}: ${error instanceof Error ? error.message : String(error)}`);
 		return undefined;
 	}
-	return parseConfigLayer(raw, path, scope, errors, warnings);
-}
-
-function readConfigLayerSync(path: string, scope: ConfigLayer["scope"], errors: string[], warnings: string[]): ConfigLayer | undefined {
-	let raw: string;
-	try {
-		raw = readFileSync(path, "utf8");
-	} catch (error) {
-		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
-			return undefined;
-		}
-		errors.push(`Could not read ${scope} config ${path}: ${error instanceof Error ? error.message : String(error)}`);
-		return undefined;
-	}
-	return parseConfigLayer(raw, path, scope, errors, warnings);
-}
-
-export function isPlaintextCredentialValue(rawValue: string): boolean {
-	const trimmed = rawValue.trim();
-	return Boolean(trimmed) && !trimmed.startsWith("!") && !trimmed.startsWith("$");
-}
-
-export function isProjectSafeCredentialValue(rawValue: string): boolean {
-	const trimmed = rawValue.trim();
-	return /^\$[A-Za-z_][A-Za-z0-9_]*$/.test(trimmed) || /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(trimmed);
-}
-
-export function classifyCredentialSource(rawValue: string, scope: AgentBrowserConfigScope): CredentialSource | undefined {
-	const trimmed = rawValue.trim();
-	if (!trimmed) return undefined;
-	if (trimmed.startsWith("!")) return { kind: "command", rawValue: trimmed, scope };
-	if (trimmed.includes("$")) return { kind: "env", rawValue: trimmed, scope };
-	return { kind: "literal", rawValue: trimmed, scope };
-}
-
-function getBrowserDefaultProfile(config: AgentBrowserConfig): Required<BrowserDefaultProfileConfig> | undefined {
-	const profile = config.browser?.defaultProfile;
-	if (!profile?.name.trim()) return undefined;
-	return { name: profile.name.trim(), policy: profile.policy ?? "authenticated-only" };
-}
-
-function buildConfigState(options: {
-	env: NodeJS.ProcessEnv;
-	layers: ConfigLayer[];
-	mergedConfig: AgentBrowserConfig;
-	paths: AgentBrowserConfigState["paths"];
-	errors: string[];
-	warnings: string[];
-}): AgentBrowserConfigState {
-	let credentialScope: AgentBrowserConfigScope = "global";
-	for (let index = options.layers.length - 1; index >= 0; index -= 1) {
-		const layer = options.layers[index];
-		if (layer?.config.webSearch?.braveApiKey !== undefined) {
-			credentialScope = layer.scope;
-			break;
-		}
-	}
-	let credentialSource = options.mergedConfig.webSearch?.braveApiKey === undefined
-		? undefined
-		: classifyCredentialSource(options.mergedConfig.webSearch.braveApiKey, credentialScope);
-	if (!credentialSource && options.env[BRAVE_API_KEY_ENV]?.trim()) {
-		credentialSource = { kind: "literal", rawValue: options.env[BRAVE_API_KEY_ENV] ?? "", scope: "env-fallback" };
-	}
-	return {
-		browserDefaultProfile: getBrowserDefaultProfile(options.mergedConfig),
-		config: options.mergedConfig,
-		credentialSource,
-		errors: options.errors,
-		layers: options.layers,
-		paths: options.paths,
-		warnings: options.warnings,
-	};
+	return parseAgentBrowserConfigLayer(raw, path, scope, errors, warnings);
 }
 
 export async function loadAgentBrowserConfig(options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}): Promise<AgentBrowserConfigState> {
@@ -313,72 +122,13 @@ export async function loadAgentBrowserConfig(options: { cwd?: string; env?: Node
 		const layer = await readConfigLayer(candidate.path, candidate.scope, errors, warnings);
 		if (!layer) continue;
 		layers.push(layer);
-		mergedConfig = mergeConfig(mergedConfig, layer.config);
+		mergedConfig = mergeAgentBrowserConfig(mergedConfig, layer.config);
 	}
-	return buildConfigState({ env, errors, layers, mergedConfig, paths, warnings });
+	return buildAgentBrowserConfigState({ env, errors, layers, mergedConfig, paths, warnings });
 }
 
 export function loadAgentBrowserConfigSync(options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}): AgentBrowserConfigState {
-	const env = options.env ?? process.env;
-	const paths = getAgentBrowserConfigPaths({ cwd: options.cwd, env });
-	const errors: string[] = [];
-	const warnings: string[] = [];
-	const layerCandidates = [
-		{ path: paths.global, scope: "global" as const },
-		{ path: paths.project, scope: "project" as const },
-		...(paths.override ? [{ path: paths.override, scope: "override" as const }] : []),
-	];
-	const layers: ConfigLayer[] = [];
-	let mergedConfig: AgentBrowserConfig = {};
-	for (const candidate of layerCandidates) {
-		const layer = readConfigLayerSync(candidate.path, candidate.scope, errors, warnings);
-		if (!layer) continue;
-		layers.push(layer);
-		mergedConfig = mergeConfig(mergedConfig, layer.config);
-	}
-	return buildConfigState({ env, errors, layers, mergedConfig, paths, warnings });
-}
-
-function resolveEnvInterpolations(rawValue: string, env: NodeJS.ProcessEnv): string | undefined {
-	let output = "";
-	for (let index = 0; index < rawValue.length; index += 1) {
-		const char = rawValue[index];
-		if (char !== "$") {
-			output += char;
-			continue;
-		}
-		const next = rawValue[index + 1];
-		if (next === "$") {
-			output += "$";
-			index += 1;
-			continue;
-		}
-		if (next === "!") {
-			output += "!";
-			index += 1;
-			continue;
-		}
-		let name = "";
-		if (next === "{") {
-			const end = rawValue.indexOf("}", index + 2);
-			if (end === -1) return undefined;
-			name = rawValue.slice(index + 2, end);
-			index = end;
-		} else {
-			const match = rawValue.slice(index + 1).match(/^([A-Za-z_][A-Za-z0-9_]*)/);
-			if (!match) {
-				output += "$";
-				continue;
-			}
-			name = match[1] ?? "";
-			index += name.length;
-		}
-		if (!name) return undefined;
-		const value = env[name];
-		if (value === undefined) return undefined;
-		output += value;
-	}
-	return output;
+	return loadAgentBrowserConfigStateSync(options);
 }
 
 async function resolveCommandCredential(rawValue: string, signal?: AbortSignal): Promise<string | undefined> {
@@ -414,33 +164,35 @@ export async function resolveCredentialSource(
 	return value ? { source, value } : undefined;
 }
 
-export async function resolveBraveApiKey(
+export async function resolveWebSearchCredential(
 	state: AgentBrowserConfigState,
+	provider: WebSearchProvider,
 	options: { env?: NodeJS.ProcessEnv; signal?: AbortSignal } = {},
 ): Promise<ResolvedCredential | undefined> {
-	return resolveCredentialSource(state.credentialSource, options);
+	return resolveCredentialSource(getWebSearchCredentialSource(state, provider), options);
 }
 
-export function canRegisterWebSearchTool(state: AgentBrowserConfigState, env: NodeJS.ProcessEnv = process.env): boolean {
-	if (!state.credentialSource || state.errors.length > 0) return false;
-	if (state.credentialSource.kind === "command") return true;
-	if (state.credentialSource.kind === "env") return Boolean(resolveEnvInterpolations(state.credentialSource.rawValue, env)?.trim());
-	return Boolean(state.credentialSource.rawValue.trim());
+export async function resolvePreferredWebSearchCredential(
+	state: AgentBrowserConfigState,
+	options: { env?: NodeJS.ProcessEnv; provider?: WebSearchProvider | "auto"; signal?: AbortSignal } = {},
+): Promise<{ provider: WebSearchProvider; credential: ResolvedCredential } | undefined> {
+	for (const provider of getWebSearchProviderOrder(state, options.provider)) {
+		const credential = await resolveWebSearchCredential(state, provider, options);
+		if (credential) return { provider, credential };
+	}
+	return undefined;
 }
 
 export async function hasResolvableCredentialSource(
 	state: AgentBrowserConfigState,
 	options: { env?: NodeJS.ProcessEnv } = {},
 ): Promise<boolean> {
-	if (!state.credentialSource || state.errors.length > 0) return false;
-	if (state.credentialSource.kind === "command") return true;
-	return Boolean((await resolveCredentialSource(state.credentialSource, options))?.value);
-}
-
-export function getCredentialSourceSummary(source: CredentialSource | undefined): string {
-	if (!source) return "not configured";
-	if (source.kind === "command") return `configured via command (${source.scope})`;
-	if (source.kind === "env") return `configured via environment interpolation (${source.scope})`;
-	if (source.scope === "env-fallback") return `configured via ${BRAVE_API_KEY_ENV} environment fallback`;
-	return `configured as plaintext ${source.scope} value [redacted]`;
+	if (!state.webSearchEnabled || state.errors.length > 0) return false;
+	for (const provider of getWebSearchProviderOrder(state)) {
+		const source = getWebSearchCredentialSource(state, provider);
+		if (!source) continue;
+		if (source.kind === "command") return true;
+		if ((await resolveCredentialSource(source, options))?.value) return true;
+	}
+	return false;
 }

package/extensions/agent-browser/lib/input-modes/params.ts

@@ -181,7 +181,7 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 	sessionMode: Type.Optional(
 		StringEnum(["auto", "fresh"] as const, {
 			description:
-				"Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device apply and later auto calls follow the new browser.",
+				"Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --profile, --executable-path, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device apply and later auto calls follow the new browser.",
 			default: DEFAULT_SESSION_MODE,
 		}),
 	),

package/extensions/agent-browser/lib/launch-scoped-flags.ts

@@ -0,0 +1,67 @@
+/**
+ * Purpose: Canonical launch-scoped agent-browser flag metadata shared by runtime planning and agent-facing guidance.
+ * Responsibilities: Define which upstream flags require a fresh launch, explain why, and expose stable guidance labels.
+ * Scope: Metadata only; argv parsing and execution planning live in runtime.ts.
+ */
+
+export interface LaunchScopedFlagDefinition {
+	flag: string;
+	reason: string;
+}
+
+export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
+	{
+		flag: "--auto-connect",
+		reason: "attaches to an already-running browser at launch time instead of reusing an existing named session",
+	},
+	{
+		flag: "--cdp",
+		reason: "selects the browser/CDP endpoint used when an upstream session is launched",
+	},
+	{
+		flag: "--enable",
+		reason: "selects built-in page init scripts before the upstream browser session is launched",
+	},
+	{
+		flag: "--executable-path",
+		reason: "selects the browser executable used for the upstream launch",
+	},
+	{
+		flag: "--init-script",
+		reason: "registers page init scripts before the upstream browser session is launched",
+	},
+	{
+		flag: "--device",
+		reason: "selects the provider device for the upstream launch",
+	},
+	{
+		flag: "--profile",
+		reason: "selects Chrome profile state for the upstream launch",
+	},
+	{
+		flag: "--provider",
+		reason: "selects the upstream browser provider for the launch",
+	},
+	{
+		flag: "-p",
+		reason: "selects the upstream browser provider for the launch",
+	},
+	{
+		flag: "--session-name",
+		reason: "selects upstream saved auth/session state for the launch",
+	},
+	{
+		flag: "--state",
+		reason: "loads persisted upstream browser/auth state at launch time",
+	},
+] as const satisfies readonly LaunchScopedFlagDefinition[];
+
+export const LAUNCH_SCOPED_FLAGS = LAUNCH_SCOPED_FLAG_DEFINITIONS.map((definition) => definition.flag);
+export const LAUNCH_SCOPED_FLAG_LABEL = LAUNCH_SCOPED_FLAGS.join(", ");
+
+/**
+ * The subset of launch-scoped flags that can restore browser/auth state with pre-existing tabs
+ * and are plausible wrong-active-tab sources after a fresh launch. These trigger post-open
+ * tab-correction (the `tab list` + re-select cycle).
+ */
+export const LAUNCH_SCOPED_TAB_CORRECTION_FLAGS = new Set(["--profile", "--session-name", "--state"] as const);