@oh-my-pi/pi-coding-agent 17.2.2 → 17.2.3

package/dist/types/modes/components/ask-dialog.d.ts

@@ -25,7 +25,6 @@ interface AskDialogOptions {
 }
 export declare class AskDialogComponent implements Component {
     #private;
-    private readonly questions;
     private readonly callbacks;
     private readonly options;
     constructor(questions: ExtensionAskDialogQuestion[], callbacks: AskDialogCallbacks, options?: AskDialogOptions);

package/dist/types/tools/browser/launch.d.ts

@@ -37,7 +37,37 @@ export interface LaunchHeadlessResult {
      */
     userDataDir?: string;
 }
+/**
+ * Base Chromium argv shared by process-local puppeteer launches and the
+ * broker-owned shared browser: sandbox/stealth flags, window size, and
+ * PUPPETEER_PROXY* env-derived proxy flags.
+ */
+export declare function buildHeadlessLaunchArgs(viewport: {
+    width: number;
+    height: number;
+}): string[];
 export declare function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<LaunchHeadlessResult>;
+/** Fully resolved executable and argv for a broker-spawned shared Chromium. */
+export interface SharedBrowserLaunchSpec {
+    executablePath: string;
+    args: string[];
+}
+/**
+ * Resolve the executable and complete argv for a shared Chromium the daemon
+ * broker spawns directly (no puppeteer inside the broker). Mirrors
+ * `launchHeadlessBrowser` flag assembly — puppeteer's default args minus the
+ * stealth-suppressed set — plus `--remote-debugging-port=0` so every client
+ * attaches over CDP. Returns null when no Chromium executable resolves;
+ * callers fall back to a process-local launch.
+ */
+export declare function resolveSharedBrowserLaunchSpec(opts: {
+    headless: boolean;
+    userDataDir: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}): Promise<SharedBrowserLaunchSpec | null>;
 /**
  * Remove an OMP-owned headless Chromium profile directory, tolerating the brief
  * window on Windows in which Chromium (or an orphaned browser subprocess) still

package/dist/types/tools/browser/registry.d.ts

@@ -25,8 +25,13 @@ export interface PuppeteerBrowserHandle extends BrowserHandleCommon {
     browser: Browser;
     cdpUrl?: string;
     pid?: number;
-    /** OMP-owned temp Chromium profile directory removed on dispose (headless launches). */
+    /** OMP-owned temp Chromium profile directory removed on dispose (process-local headless launches). */
     userDataDir?: string;
+    /** Broker daemon backing this handle; dispose disconnects instead of closing, kill routes to the broker. */
+    sharedDaemon?: {
+        name: string;
+        projectDir: string;
+    };
     subprocess?: Subprocess;
     stealth: {
         browserSession: CDPSession | null;

package/dist/types/tools/browser/shared-daemon.d.ts

@@ -0,0 +1,26 @@
+/** Broker-owned browser endpoint one omp process can attach to. */
+export interface SharedBrowserEndpoint {
+    wsEndpoint: string;
+    daemonName: string;
+    /** Canonical project directory owning the broker (used to address later stop requests). */
+    projectDir: string;
+}
+/** Stable broker daemon name for the shared automation browser. */
+export declare function sharedBrowserDaemonName(headless: boolean): string;
+/**
+ * Ensure the project-shared automation Chromium is running and reachable,
+ * launching it under the daemon broker when needed. Idempotent across
+ * processes: losers of the start race adopt the winner's endpoint on the next
+ * describe round. Returns null when the shared path is unavailable (no
+ * resolvable Chromium, broker failure, or a daemon that never becomes
+ * reachable); callers fall back to a process-local launch.
+ */
+export declare function ensureSharedBrowser(opts: {
+    projectDir: string;
+    headless: boolean;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    signal?: AbortSignal;
+}): Promise<SharedBrowserEndpoint | null>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "17.2.2",
+	"version": "17.2.3",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -52,17 +52,17 @@
 		"@agentclientprotocol/sdk": "1.2.1",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "17.2.2",
-		"@oh-my-pi/omp-stats": "17.2.2",
-		"@oh-my-pi/pi-agent-core": "17.2.2",
-		"@oh-my-pi/pi-ai": "17.2.2",
-		"@oh-my-pi/pi-catalog": "17.2.2",
-		"@oh-my-pi/pi-mnemopi": "17.2.2",
-		"@oh-my-pi/pi-natives": "17.2.2",
-		"@oh-my-pi/pi-tui": "17.2.2",
-		"@oh-my-pi/pi-utils": "17.2.2",
-		"@oh-my-pi/pi-wire": "17.2.2",
-		"@oh-my-pi/snapcompact": "17.2.2",
+		"@oh-my-pi/hashline": "17.2.3",
+		"@oh-my-pi/omp-stats": "17.2.3",
+		"@oh-my-pi/pi-agent-core": "17.2.3",
+		"@oh-my-pi/pi-ai": "17.2.3",
+		"@oh-my-pi/pi-catalog": "17.2.3",
+		"@oh-my-pi/pi-mnemopi": "17.2.3",
+		"@oh-my-pi/pi-natives": "17.2.3",
+		"@oh-my-pi/pi-tui": "17.2.3",
+		"@oh-my-pi/pi-utils": "17.2.3",
+		"@oh-my-pi/pi-wire": "17.2.3",
+		"@oh-my-pi/snapcompact": "17.2.3",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/api-logs": "^0.220.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",

package/src/launch/broker.ts

@@ -342,6 +342,15 @@ class DaemonBroker {
 	readonly #token: string;
 	readonly #idleGraceMs: number;
 	readonly #records = new Map<string, ManagedDaemon>();
+	/**
+	 * Names reserved by an in-flight `start` before its record lands in
+	 * `#records`. Requests dispatch concurrently, and `#start` awaits (cwd stat,
+	 * log open) between the duplicate check and the record insert; without a
+	 * synchronous reservation two clients can both pass the check and spawn
+	 * duplicate processes — one exits on a held resource (e.g. a Chromium
+	 * profile lock) or keeps running untracked.
+	 */
+	readonly #startingNames = new Set<string>();
 	readonly #clients = new Set<net.Socket>();
 	readonly #finished = Promise.withResolvers<void>();
 	readonly #sockets = new Set<net.Socket>();
@@ -500,50 +509,59 @@ class DaemonBroker {
 		) {
 			throw new Error('Windows batch files require application "cmd.exe" with the batch path after "/c"');
 		}
-		const existing = this.#records.get(spec.name);
-		if (existing) await this.#refreshDetached(existing);
-		if (existing && !terminalState(existing.snapshot.state)) {
-			throw new Error(`Daemon ${spec.name} is already ${existing.snapshot.state}`);
+		if (this.#startingNames.has(spec.name)) {
+			throw new Error(`Daemon ${spec.name} is already starting`);
 		}
-		if (spec.ready?.log) {
-			try {
-				new RegExp(spec.ready.log, "u");
-			} catch (error) {
-				throw new Error(`Invalid readiness regex: ${error instanceof Error ? error.message : String(error)}`);
+		this.#startingNames.add(spec.name);
+		let record: ManagedDaemon;
+		try {
+			const existing = this.#records.get(spec.name);
+			if (existing) await this.#refreshDetached(existing);
+			if (existing && !terminalState(existing.snapshot.state)) {
+				throw new Error(`Daemon ${spec.name} is already ${existing.snapshot.state}`);
+			}
+			if (spec.ready?.log) {
+				try {
+					new RegExp(spec.ready.log, "u");
+				} catch (error) {
+					throw new Error(`Invalid readiness regex: ${error instanceof Error ? error.message : String(error)}`);
+				}
 			}
+			const stat = await fs.stat(spec.cwd);
+			if (!stat.isDirectory()) throw new Error(`Daemon cwd is not a directory: ${spec.cwd}`);
+			const dir = path.join(this.#runtimeDir, "daemons", spec.name);
+			const now = Date.now();
+			record = {
+				spec,
+				snapshot: {
+					name: spec.name,
+					id: crypto.randomUUID(),
+					state: "starting",
+					createdAt: now,
+					startedAt: now,
+					restartCount: 0,
+					outputBytes: 0,
+					owner,
+					persist: spec.persist,
+					detached: spec.detached,
+				},
+				dir,
+				log: await DaemonLog.open(dir),
+				generation: 0,
+				stopRequested: false,
+				logReady: !spec.ready?.log,
+				portReady: spec.ready?.port === undefined,
+				readinessBuffer: "",
+				outputOffset: 0,
+				readyPattern: spec.ready?.log ? new RegExp(spec.ready.log, "u") : undefined,
+				consecutiveFailures: 0,
+				persistQueue: Promise.resolve(),
+			};
+			syncReadyPending(record);
+			this.#records.set(spec.name, record);
+		} finally {
+			this.#startingNames.delete(spec.name);
 		}
-		const stat = await fs.stat(spec.cwd);
-		if (!stat.isDirectory()) throw new Error(`Daemon cwd is not a directory: ${spec.cwd}`);
-		const dir = path.join(this.#runtimeDir, "daemons", spec.name);
-		const now = Date.now();
-		const record: ManagedDaemon = {
-			spec,
-			snapshot: {
-				name: spec.name,
-				id: crypto.randomUUID(),
-				state: "starting",
-				createdAt: now,
-				startedAt: now,
-				restartCount: 0,
-				outputBytes: 0,
-				owner,
-				persist: spec.persist,
-				detached: spec.detached,
-			},
-			dir,
-			log: await DaemonLog.open(dir),
-			generation: 0,
-			stopRequested: false,
-			logReady: !spec.ready?.log,
-			portReady: spec.ready?.port === undefined,
-			readinessBuffer: "",
-			outputOffset: 0,
-			readyPattern: spec.ready?.log ? new RegExp(spec.ready.log, "u") : undefined,
-			consecutiveFailures: 0,
-			persistQueue: Promise.resolve(),
-		};
-		syncReadyPending(record);
-		this.#records.set(spec.name, record);
 		await this.#launch(record);
 		let readyTimedOut = false;
 		if (spec.ready && !terminalState(record.snapshot.state)) {

package/src/modes/components/ask-dialog.ts

@@ -15,6 +15,7 @@ import {
 	wrapTextWithAnsi,
 } from "@oh-my-pi/pi-tui";
 import type {
+	ExtensionAskDialogOption,
 	ExtensionAskDialogQuestion,
 	ExtensionAskDialogResultItem,
 	ExtensionAskDialogSubmitResult,
@@ -337,6 +338,45 @@ function renderRowLabel(
 	return lines;
 }
 
+/**
+ * Coerce untrusted dialog questions into a render-safe shape. The live ask
+ * dialog is reached from the public `askDialog` extension surface and from
+ * streamed tool args, where a question entry can arrive with a missing or
+ * non-string `question` field. The render helpers (`replaceTabs`,
+ * `renderQuestionTitle`, `questionTabLabel`) assume strings, so a malformed
+ * entry throws and takes down the whole TUI render loop. Mirrors
+ * `normalizeRenderQuestions` on the transcript path.
+ */
+function normalizeDialogQuestions(questions: ExtensionAskDialogQuestion[]): ExtensionAskDialogQuestion[] {
+	if (!Array.isArray(questions)) return [];
+	const out: ExtensionAskDialogQuestion[] = [];
+	for (const entry of questions) {
+		if (!entry || typeof entry !== "object") continue;
+		const q = entry as Partial<ExtensionAskDialogQuestion>;
+		const options: ExtensionAskDialogOption[] = [];
+		if (Array.isArray(q.options)) {
+			for (const opt of q.options) {
+				if (!opt || typeof opt !== "object") continue;
+				const o = opt as Partial<ExtensionAskDialogOption>;
+				options.push({
+					label: typeof o.label === "string" ? o.label : "",
+					...(typeof o.description === "string" ? { description: o.description } : {}),
+					...(typeof o.preview === "string" ? { preview: o.preview } : {}),
+				});
+			}
+		}
+		out.push({
+			id: typeof q.id === "string" ? q.id : "?",
+			question: typeof q.question === "string" ? q.question : "",
+			...(typeof q.header === "string" ? { header: q.header } : {}),
+			options,
+			...(typeof q.multi === "boolean" ? { multi: q.multi } : {}),
+			...(Number.isInteger(q.recommended) ? { recommended: q.recommended } : {}),
+		});
+	}
+	return out;
+}
+
 export class AskDialogComponent implements Component {
 	#states: QuestionState[];
 	#activeTabIndex = 0;
@@ -352,13 +392,15 @@ export class AskDialogComponent implements Component {
 	#stableHeight: { key: string; total: number } | undefined;
 	#previewCache: PreviewRenderCache = new Map();
 	#overflowLayouts = new WeakMap<ExtensionAskDialogQuestion, Set<string>>();
+	readonly #questions: ExtensionAskDialogQuestion[];
 
 	constructor(
-		private readonly questions: ExtensionAskDialogQuestion[],
+		questions: ExtensionAskDialogQuestion[],
 		private readonly callbacks: AskDialogCallbacks,
 		private readonly options: AskDialogOptions = {},
 	) {
-		this.#states = questions.map(question => {
+		this.#questions = normalizeDialogQuestions(questions);
+		this.#states = this.#questions.map(question => {
 			const recommended = Number.isInteger(question.recommended) ? question.recommended : 0;
 			const maxIndex = Math.max(0, question.options.length - 1);
 			return {
@@ -474,8 +516,8 @@ export class AskDialogComponent implements Component {
 		const tabBarRows = this.#hasSubmitTab() ? 1 : 0;
 		const mdTheme = getMarkdownTheme();
 		let needed = MIN_DIALOG_ROWS;
-		for (let index = 0; index < this.questions.length; index++) {
-			const question = this.questions[index];
+		for (let index = 0; index < this.#questions.length; index++) {
+			const question = this.#questions[index];
 			const state = this.#states[index];
 			if (!question || !state) continue;
 			const headerRows = tabBarRows + renderQuestionTitle(question, width).length;
@@ -493,7 +535,7 @@ export class AskDialogComponent implements Component {
 		if (this.#hasSubmitTab()) {
 			// Warning line + blank, one summary line per question, blank, and
 			// the Submit row; note lines added later scroll within the body.
-			const body = 2 + this.questions.length + 2;
+			const body = 2 + this.#questions.length + 2;
 			needed = Math.max(needed, chrome + tabBarRows + 1 + Math.max(MIN_BODY_ROWS, body));
 		}
 		return Math.min(needed, maxHeight);
@@ -507,11 +549,11 @@ export class AskDialogComponent implements Component {
 		// Multi questions confirm on the Submit tab (Enter toggles, never
 		// submits), so any multi question forces the tab even when there is
 		// only one question.
-		return this.questions.length > 1 || this.questions.some(question => question.multi);
+		return this.#questions.length > 1 || this.#questions.some(question => question.multi);
 	}
 
 	#submitTabIndex(): number {
-		return this.questions.length;
+		return this.#questions.length;
 	}
 
 	#isSubmitTab(): boolean {
@@ -519,7 +561,7 @@ export class AskDialogComponent implements Component {
 	}
 
 	#currentQuestionIndex(): number {
-		return clamp(this.#activeTabIndex, 0, Math.max(0, this.questions.length - 1));
+		return clamp(this.#activeTabIndex, 0, Math.max(0, this.#questions.length - 1));
 	}
 
 	#requestRender(): void {
@@ -530,7 +572,7 @@ export class AskDialogComponent implements Component {
 		const lines: string[] = [];
 		if (this.#hasSubmitTab()) {
 			const tabs: Tab[] = [
-				...this.questions.map((question, index) => ({
+				...this.#questions.map((question, index) => ({
 					id: String(index),
 					label: questionTabLabel(question, index),
 				})),
@@ -545,7 +587,7 @@ export class AskDialogComponent implements Component {
 			return lines;
 		}
 		const questionIndex = this.#currentQuestionIndex();
-		const question = this.questions[questionIndex];
+		const question = this.#questions[questionIndex];
 		if (!question) return lines;
 		lines.push(...renderQuestionTitle(question, width));
 		return lines;
@@ -559,7 +601,7 @@ export class AskDialogComponent implements Component {
 			const scroll = indicator ? ` ${indicator} scroll ·` : "";
 			return `Enter submit · ↑/↓ scroll ·${scroll} ${cancel}`;
 		}
-		const question = this.questions[this.#currentQuestionIndex()];
+		const question = this.#questions[this.#currentQuestionIndex()];
 		const action = question?.multi ? "Space/Enter toggle · n note" : "Enter select · n note";
 		const tabs = this.#hasSubmitTab() ? " · Tab/←/→" : "";
 		if (this.#questionCanPage && indicator) {
@@ -585,7 +627,7 @@ export class AskDialogComponent implements Component {
 	}
 
 	#activeQuestionState(): { question: ExtensionAskDialogQuestion; state: QuestionState } | undefined {
-		const question = this.questions[this.#currentQuestionIndex()];
+		const question = this.#questions[this.#currentQuestionIndex()];
 		const state = this.#states[this.#currentQuestionIndex()];
 		if (!question || !state) return undefined;
 		return { question, state };
@@ -672,18 +714,18 @@ export class AskDialogComponent implements Component {
 	}
 
 	#switchTab(direction: 1 | -1): void {
-		const tabCount = this.questions.length + 1;
+		const tabCount = this.#questions.length + 1;
 		this.#activeTabIndex = (this.#activeTabIndex + direction + tabCount) % tabCount;
 		this.#submitScrollOffset = 0;
 	}
 
 	#advanceAfterQuestion(): void {
 		const current = this.#currentQuestionIndex();
-		if (this.questions.length === 1) {
+		if (this.#questions.length === 1) {
 			this.#finishSubmit();
 			return;
 		}
-		this.#activeTabIndex = current + 1 < this.questions.length ? current + 1 : this.#submitTabIndex();
+		this.#activeTabIndex = current + 1 < this.#questions.length ? current + 1 : this.#submitTabIndex();
 		this.#submitScrollOffset = 0;
 		this.#requestRender();
 	}
@@ -829,8 +871,8 @@ export class AskDialogComponent implements Component {
 			);
 			allLines.push("");
 		}
-		for (let index = 0; index < this.questions.length; index++) {
-			const question = this.questions[index];
+		for (let index = 0; index < this.#questions.length; index++) {
+			const question = this.#questions[index];
 			const state = this.#states[index];
 			if (!question || !state) continue;
 			const label = questionTabLabel(question, index);
@@ -895,8 +937,8 @@ export class AskDialogComponent implements Component {
 
 	#unansweredCount(): number {
 		let count = 0;
-		for (let index = 0; index < this.questions.length; index++) {
-			const question = this.questions[index];
+		for (let index = 0; index < this.#questions.length; index++) {
+			const question = this.#questions[index];
 			const state = this.#states[index];
 			if (!question || !state) continue;
 			if (state.selectedOptions.size === 0 && state.customInput === undefined) count += 1;
@@ -911,8 +953,8 @@ export class AskDialogComponent implements Component {
 			return;
 		}
 		this.options.onTimeout?.();
-		for (let index = 0; index < this.questions.length; index++) {
-			const question = this.questions[index];
+		for (let index = 0; index < this.#questions.length; index++) {
+			const question = this.#questions[index];
 			const state = this.#states[index];
 			if (!question || !state) continue;
 			if (state.selectedOptions.size === 0 && state.customInput === undefined) {
@@ -952,8 +994,8 @@ export class AskDialogComponent implements Component {
 
 	#buildResults(): ExtensionAskDialogResultItem[] {
 		const results: ExtensionAskDialogResultItem[] = [];
-		for (let index = 0; index < this.questions.length; index++) {
-			const question = this.questions[index];
+		for (let index = 0; index < this.#questions.length; index++) {
+			const question = this.#questions[index];
 			const state = this.#states[index];
 			if (!question || !state) continue;
 			const selectedOptions = question.options

package/src/session/agent-session.ts

@@ -7018,7 +7018,7 @@ export class AgentSession {
 				// shared provider state map is still required so Codex can allocate
 				// websocket state under that side-channel session id.
 				sessionId: `${cacheSessionId}:side:${Snowflake.next()}`,
-				promptCacheKey: cacheSessionId,
+				promptCacheKey: this.agent.promptCacheKey ?? this.agent.sessionId,
 				preferWebsockets: this.#preferWebsockets,
 				providerSessionState: this.#providerSessionState,
 				reasoning: toReasoningEffort(this.thinkingLevel),

package/src/session/session-maintenance.ts

@@ -1539,7 +1539,7 @@ export class SessionMaintenance {
 						thinkingLevel: this.#host.thinkingLevel(),
 						tools: this.#host.agent.state.tools,
 						sessionId: this.#host.sessionId(),
-						promptCacheKey: this.#host.sessionId(),
+						promptCacheKey: this.#host.agent.promptCacheKey ?? this.#host.agent.sessionId,
 						providerSessionState: this.#host.providerSessionState,
 						// Route every summarization HTTP request through the
 						// session's side-stream transport so the provider
@@ -2585,7 +2585,7 @@ export class SessionMaintenance {
 									thinkingLevel: this.#host.thinkingLevel(),
 									tools: this.#host.agent.state.tools,
 									sessionId: this.#host.sessionId(),
-									promptCacheKey: this.#host.sessionId(),
+									promptCacheKey: this.#host.agent.promptCacheKey ?? this.#host.agent.sessionId,
 									providerSessionState: this.#host.providerSessionState,
 									codexCompaction,
 								},

package/src/tools/bash.ts

@@ -843,13 +843,18 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 			return { kind: "steer" };
 		}
 
+		// Cancellable threshold: a bare Bun.sleep(thresholdMs) leaves a live, ref'd
+		// timer for the full threshold after the command finishes (or abort/steer)
+		// wins the race first — delaying SDK/headless shutdown and accumulating
+		// timers under fast command rates. Settle a withResolvers promise from
+		// setTimeout so the finally can clear it regardless of which waiter wins.
+		const { promise: thresholdPromise, resolve: resolveThreshold } = Promise.withResolvers<{
+			kind: "running";
+		}>();
+		const thresholdTimer = setTimeout(() => resolveThreshold({ kind: "running" }), thresholdMs);
 		const waiters: Array<
 			Promise<ManagedBashJobCompletion | { kind: "running" } | { kind: "steer" } | { kind: "aborted" }>
-		> = [job.completion, Bun.sleep(thresholdMs).then(() => ({ kind: "running" as const }))];
-
-		if (!signal && !steeringSignal) {
-			return await Promise.race(waiters);
-		}
+		> = [job.completion, thresholdPromise];
 
 		const { promise: abortedPromise, resolve: resolveAborted } = Promise.withResolvers<{ kind: "aborted" }>();
 		const onAbort = () => resolveAborted({ kind: "aborted" });
@@ -866,6 +871,7 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		try {
 			return await Promise.race(waiters);
 		} finally {
+			clearTimeout(thresholdTimer);
 			signal?.removeEventListener("abort", onAbort);
 			steeringSignal?.removeEventListener("abort", onSteer);
 		}

package/src/tools/browser/launch.ts

@@ -296,19 +296,17 @@ export interface LaunchHeadlessResult {
 	userDataDir?: string;
 }
 
-export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<LaunchHeadlessResult> {
-	const vp = opts.viewport ?? DEFAULT_VIEWPORT;
-	const initialViewport = {
-		width: vp.width,
-		height: vp.height,
-		deviceScaleFactor: vp.deviceScaleFactor ?? DEFAULT_VIEWPORT.deviceScaleFactor,
-	};
-	const puppeteer = await loadPuppeteer();
+/**
+ * Base Chromium argv shared by process-local puppeteer launches and the
+ * broker-owned shared browser: sandbox/stealth flags, window size, and
+ * PUPPETEER_PROXY* env-derived proxy flags.
+ */
+export function buildHeadlessLaunchArgs(viewport: { width: number; height: number }): string[] {
 	const launchArgs = [
 		"--no-sandbox",
 		"--disable-setuid-sandbox",
 		"--disable-blink-features=AutomationControlled",
-		`--window-size=${initialViewport.width},${initialViewport.height}`,
+		`--window-size=${viewport.width},${viewport.height}`,
 	];
 	const proxy = process.env.PUPPETEER_PROXY;
 	if (proxy) {
@@ -324,6 +322,18 @@ export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promis
 	if (ignoreCert === "true" || ignoreCert === "1" || ignoreCert === "yes" || ignoreCert === "on") {
 		launchArgs.push("--ignore-certificate-errors");
 	}
+	return launchArgs;
+}
+
+export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<LaunchHeadlessResult> {
+	const vp = opts.viewport ?? DEFAULT_VIEWPORT;
+	const initialViewport = {
+		width: vp.width,
+		height: vp.height,
+		deviceScaleFactor: vp.deviceScaleFactor ?? DEFAULT_VIEWPORT.deviceScaleFactor,
+	};
+	const puppeteer = await loadPuppeteer();
+	const launchArgs = buildHeadlessLaunchArgs(initialViewport);
 	for (const arg of opts.args ?? []) {
 		if (!launchArgs.includes(arg)) launchArgs.push(arg);
 	}
@@ -357,6 +367,41 @@ export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promis
 	}
 }
 
+/** Fully resolved executable and argv for a broker-spawned shared Chromium. */
+export interface SharedBrowserLaunchSpec {
+	executablePath: string;
+	args: string[];
+}
+
+/**
+ * Resolve the executable and complete argv for a shared Chromium the daemon
+ * broker spawns directly (no puppeteer inside the broker). Mirrors
+ * `launchHeadlessBrowser` flag assembly — puppeteer's default args minus the
+ * stealth-suppressed set — plus `--remote-debugging-port=0` so every client
+ * attaches over CDP. Returns null when no Chromium executable resolves;
+ * callers fall back to a process-local launch.
+ */
+export async function resolveSharedBrowserLaunchSpec(opts: {
+	headless: boolean;
+	userDataDir: string;
+	viewport?: { width: number; height: number };
+}): Promise<SharedBrowserLaunchSpec | null> {
+	const executablePath = await ensureChromiumExecutable();
+	if (!executablePath) return null;
+	const puppeteer = await loadPuppeteer();
+	const vp = opts.viewport ?? DEFAULT_VIEWPORT;
+	const ignored = new Set(stealthIgnoreDefaultArgs(executablePath));
+	const defaults = await puppeteer.defaultArgs({
+		headless: opts.headless,
+		args: buildHeadlessLaunchArgs(vp),
+		userDataDir: opts.userDataDir,
+	});
+	return {
+		executablePath,
+		args: [...defaults.filter(arg => !ignored.has(arg)), "--remote-debugging-port=0"],
+	};
+}
+
 /**
  * Remove an OMP-owned headless Chromium profile directory, tolerating the brief
  * window on Windows in which Chromium (or an orphaned browser subprocess) still