@geometra/mcp 1.61.2 → 1.62.1

package/README.md

@@ -18,14 +18,14 @@ Geometra proxy:       Chromium → DOM geometry → same WebSocket as native →
 
 Use Geometra MCP when an LLM needs to explore, interpret, and operate a real UI with compact semantic state instead of repeatedly consuming large browser snapshots. Keep Playwright-style tooling for deterministic scripts, DOM-oriented test automation, and compatibility fallback paths while Geometra closes remaining live-site gaps.
 
-Proxy-backed sessions stay warm by default on disconnect, and MCP now keeps a small warm pool so compatible headed and headless workflows do not immediately evict each other.
+Proxy-backed sessions stay warm by default on disconnect, and MCP now keeps a small warm pool so compatible headed, headless, and stealth workflows do not immediately evict each other.
 
 ## Tools
 
 | Tool | Description |
 |---|---|
-| `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; can inline `formSchema` and/or `pageModel`, or defer the page model for a faster first connect response |
-| `geometra_prepare_browser` | Pre-launch and pre-navigate a reusable proxy/browser for `pageUrl` without creating an active session; best when the agent can prepare before the user-facing task starts |
+| `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; pass `stealth: true` for CloakBrowser's patched Chromium; can inline `formSchema` and/or `pageModel`, or defer the page model for a faster first connect response |
+| `geometra_prepare_browser` | Pre-launch and pre-navigate a reusable proxy/browser for `pageUrl` without creating an active session; supports the same headed/headless/stealth browser settings as `geometra_connect` |
 | `geometra_query` | Find elements by stable id, role, name, text content, prompt/section/item context, current value, or semantic state such as `invalid`, `required`, or `busy` |
 | `geometra_wait_for` | Wait for a semantic condition instead of guessing sleeps (`busy`, `disabled`, alerts, values, etc.). **Strict parameters** — use `text` plus `present: false` to wait until a substring disappears (e.g. “Parsing your resume”); there is no `textGone` field |
 | `geometra_wait_for_resume_parse` | Convenience wait until a parsing banner is gone (defaults: `text`: `"Parsing"`, `present` implied false). Same engine as `geometra_wait_for` |
@@ -252,9 +252,10 @@ In another terminal (from repo root after `npm install` / `bun install` and `bun
 ```bash
 npx geometra-proxy http://localhost:8080 --port 3200
 # Requires Chromium: npx playwright install chromium
+# Optional stealth prefetch: npx cloakbrowser install
 ```
 
-`geometra-proxy` opens a **visible Chromium window by default**. For servers or CI, pass **`--headless`** or set **`GEOMETRA_HEADLESS=1`**. Optional **`--slow-mo <ms>`** slows Playwright actions so they are easier to watch. Headed vs headless usually does **not** materially change token usage, since token usage is driven by MCP tool output rather than whether Chromium is visible.
+`geometra-proxy` opens a **visible Chromium window by default**. For servers or CI, pass **`--headless`** or set **`GEOMETRA_HEADLESS=1`**. Pass **`--stealth`**, **`stealth: true`** on MCP tools, or **`GEOMETRA_STEALTH=1`** to use CloakBrowser's patched Chromium through the same proxy protocol. Optional **`--slow-mo <ms>`** slows Playwright actions so they are easier to watch. Headed vs headless usually does **not** materially change token usage, since token usage is driven by MCP tool output rather than whether Chromium is visible.
 
 Point MCP at `ws://127.0.0.1:3200` instead of a native Geometra server. The proxy translates clicks and keyboard messages into Playwright actions and streams updated geometry.
 
@@ -341,7 +342,7 @@ For long application flows, prefer one of these patterns:
 4. `geometra_snapshot({ view: "form-required" })` when you need the remaining required fields including offscreen ones
 5. `geometra_reveal` for far-below-fold targets such as submit buttons (auto-scales reveal steps when you omit `maxSteps`)
 6. `geometra_click({ ..., waitFor: ... })` when one action should also wait for the next semantic state
-7. `geometra_prepare_browser({ pageUrl, headless, width, height })` when you can hide browser startup before the real task and want the next proxy-backed flow to attach warm
+7. `geometra_prepare_browser({ pageUrl, headless, stealth, width, height })` when you can hide browser startup before the real task and want the next proxy-backed flow to attach warm
 8. `geometra_run_actions` when you need mixed navigation + waits + field entry, especially with `pageUrl` / `url` for a one-call flow
 9. `geometra_connect({ pageUrl, returnPageModel: true })` when you want connect + summary-first exploration in one turn
 10. `geometra_connect({ pageUrl, returnPageModel: true, pageModelMode: "deferred" })` when first-response latency matters more than inlining the page model; follow with `geometra_page_model`

package/dist/proxy-spawn.d.ts

@@ -31,14 +31,18 @@ export interface SpawnProxyParams {
     width?: number;
     height?: number;
     slowMo?: number;
+    stealth?: boolean;
     eagerInitialExtract?: boolean;
     proxy?: SpawnProxyConfig;
 }
+export declare function resolveStealthMode(stealth?: boolean): boolean;
 export declare function startEmbeddedGeometraProxy(opts: SpawnProxyParams): Promise<{
     runtime: EmbeddedProxyRuntime;
     wsUrl: string;
 }>;
-export declare function parseProxyReadySignalLine(line: string): string | undefined;
+export declare function parseProxyReadySignalLine(line: string, options?: {
+    allowLegacy?: boolean;
+}): string | undefined;
 export declare function formatProxyStartupFailure(message: string, opts: SpawnProxyParams): string;
 /**
  * Spawn geometra-proxy as a child process and resolve when it emits a structured ready signal.

package/dist/proxy-spawn.js

@@ -7,6 +7,7 @@ const require = createRequire(import.meta.url);
 const READY_SIGNAL_TYPE = 'geometra-proxy-ready';
 const READY_TIMEOUT_MS = 45_000;
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PLAYWRIGHT_INSTALL_HINT = 'Install Chromium with the Playwright version bundled in this package: npm run browsers:install -w @geometra/proxy (repo checkout) or npx --no-install playwright install chromium.';
 /** Resolve bundled @geometra/proxy CLI entry (dist/index.js). */
 export function resolveProxyScriptPath() {
     return resolveProxyScriptPathWith(require);
@@ -125,6 +126,9 @@ function buildLocalProxyDistIfPossible(packageDir, entryFile, errors) {
     }
     return undefined;
 }
+export function resolveStealthMode(stealth) {
+    return stealth ?? true;
+}
 export async function startEmbeddedGeometraProxy(opts) {
     const runtimePath = resolveProxyRuntimePath();
     const runtimeModule = await import(pathToFileURL(runtimePath).href);
@@ -136,14 +140,15 @@ export async function startEmbeddedGeometraProxy(opts) {
         port: opts.port,
         width: opts.width,
         height: opts.height,
-        headed: opts.headless !== true,
+        headed: opts.headless === false,
         slowMo: opts.slowMo,
+        ...(opts.stealth !== undefined && { stealth: opts.stealth }),
         eagerInitialExtract: opts.eagerInitialExtract,
         ...(opts.proxy && { proxy: opts.proxy }),
     });
     return { runtime, wsUrl: runtime.wsUrl };
 }
-export function parseProxyReadySignalLine(line) {
+export function parseProxyReadySignalLine(line, options) {
     const trimmed = line.trim();
     if (!trimmed)
         return undefined;
@@ -160,13 +165,18 @@ export function parseProxyReadySignalLine(line) {
             /* ignore non-JSON lines */
         }
     }
+    if (options?.allowLegacy === false)
+        return undefined;
     const fallback = trimmed.match(/WebSocket listening on (ws:\/\/127\.0\.0\.1:\d+)/);
     return fallback?.[1];
 }
 export function formatProxyStartupFailure(message, opts) {
     const hints = [];
     if (/Executable doesn't exist|playwright install chromium|browserType\.launch/i.test(message)) {
-        hints.push('Install Chromium with: npx playwright install chromium');
+        hints.push(PLAYWRIGHT_INSTALL_HINT);
+    }
+    if (/cloakbrowser|CLOAKBROWSER|ERR_MODULE_NOT_FOUND|Cannot find package/i.test(message)) {
+        hints.push('Stealth mode uses CloakBrowser. Install dependencies with npm install, or disable stealth with stealth=false / GEOMETRA_STEALTH=0. To prefetch the patched Chromium binary, run: npx cloakbrowser install');
     }
     if (opts.port > 0 && /EADDRINUSE|address already in use/i.test(message)) {
         hints.push(`Requested port ${opts.port} is unavailable. Omit the port to use an ephemeral OS-assigned port, or choose another local port.`);
@@ -187,10 +197,14 @@ export function spawnGeometraProxy(opts) {
         args.push('--height', String(opts.height));
     if (opts.slowMo != null && opts.slowMo > 0)
         args.push('--slow-mo', String(opts.slowMo));
-    if (opts.headless === true)
-        args.push('--headless');
-    else if (opts.headless === false)
+    if (opts.headless === false)
         args.push('--headed');
+    else
+        args.push('--headless');
+    if (opts.stealth === true)
+        args.push('--stealth');
+    else if (opts.stealth === false)
+        args.push('--no-stealth');
     if (opts.eagerInitialExtract === false)
         args.push('--lazy-initial-extract');
     if (opts.proxy?.server) {
@@ -216,7 +230,7 @@ export function spawnGeometraProxy(opts) {
             child.stderr?.removeAllListeners('data');
         };
         const tryResolveReady = (line) => {
-            const wsUrl = parseProxyReadySignalLine(line);
+            const wsUrl = parseProxyReadySignalLine(line, { allowLegacy: false });
             if (!wsUrl || settled)
                 return false;
             settled = true;

package/dist/server.js

@@ -17,6 +17,12 @@ function detailInput() {
         .default('minimal')
         .describe('`terse` returns compact machine-friendly JSON. `minimal` (default) returns short human-readable summaries. `verbose` adds fuller fallback context.');
 }
+function stealthInput() {
+    return z
+        .boolean()
+        .optional()
+        .describe('Launch CloakBrowser stealth Chromium for proxy-backed pageUrl sessions. Default false unless GEOMETRA_STEALTH=1 or GEOMETRA_BROWSER=stealth is set.');
+}
 function formSchemaFormatInput() {
     return z
         .enum(['compact', 'packed'])
@@ -401,7 +407,7 @@ export function createServer() {
 
 Use \`url\` (ws://…) only when a Geometra/native server or an already-running proxy is listening. If you accidentally pass \`https://…\` in \`url\`, MCP treats it like \`pageUrl\` and starts the proxy for you.
 
-Chromium opens **visible** by default unless \`headless: true\`. File upload / wheel / native \`<select>\` need the proxy path (\`pageUrl\` or ws to proxy). Set \`returnForms: true\` and/or \`returnPageModel: true\` when you want a lower-turn startup response. When connect first-response latency matters more than inlining the page model, pair \`returnPageModel: true\` with \`pageModelMode: "deferred"\` and call \`geometra_page_model\` next.
+Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth: true\` (or set \`GEOMETRA_STEALTH=1\`) to launch CloakBrowser's patched Chromium instead of stock Playwright Chromium. File upload / wheel / native \`<select>\` need the proxy path (\`pageUrl\` or ws to proxy). Set \`returnForms: true\` and/or \`returnPageModel: true\` when you want a lower-turn startup response. When connect first-response latency matters more than inlining the page model, pair \`returnPageModel: true\` with \`pageModelMode: "deferred"\` and call \`geometra_page_model\` next.
 
 **Parallelism:** by default, geometra MCP pools and reuses Chromium instances across sessions for speed. That pooling is safe for read-only exploration, but it shares localStorage / cookies / page state across whichever sessions land on the same proxy — which means **two parallel form-submission flows can contaminate each other** (one job's email/autocomplete state leaks into another, or worse, two agents end up driving the same browser tab). For parallel apply / form submission, pass \`isolated: true\`. Each isolated session gets its own brand-new Chromium that is destroyed on disconnect, never enters the pool, and is guaranteed independent of every other session. The cost is ~1–2s of extra startup vs the ~50ms reusable-proxy attach.`, {
         url: z
@@ -433,6 +439,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             .nonnegative()
             .optional()
             .describe('Playwright slowMo (ms) on spawned proxy for easier visual following.'),
+        stealth: stealthInput(),
         isolated: z
             .boolean()
             .optional()
@@ -506,6 +513,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                     width: input.width,
                     height: input.height,
                     slowMo: input.slowMo,
+                    ...(input.stealth !== undefined && { stealth: input.stealth }),
                     isolated: input.isolated,
                     proxy: input.proxy,
                     awaitInitialFrame: deferInlinePageModel ? false : undefined,
@@ -578,6 +586,7 @@ Use this when you can prepare ahead of the user-facing task so the next \`geomet
             .nonnegative()
             .optional()
             .describe('Playwright slowMo (ms) for the warmed browser.'),
+        stealth: stealthInput(),
         proxy: z
             .object({
             server: z
@@ -592,9 +601,18 @@ Use this when you can prepare ahead of the user-facing task so the next \`geomet
         })
             .optional()
             .describe('BYO outbound proxy for the warmed Chromium. The pool entry is partitioned by proxy identity, so a later geometra_connect with the same proxy config will reuse this warmed browser; a different proxy config (or no proxy) will not.'),
-    }, async ({ pageUrl, port, headless, width, height, slowMo, proxy }) => {
+    }, async ({ pageUrl, port, headless, width, height, slowMo, stealth, proxy }) => {
         try {
-            const prepared = await prewarmProxy({ pageUrl, port, headless, width, height, slowMo, proxy });
+            const prepared = await prewarmProxy({
+                pageUrl,
+                port,
+                headless,
+                width,
+                height,
+                slowMo,
+                ...(stealth !== undefined && { stealth }),
+                proxy,
+            });
             return ok(JSON.stringify(prepared));
         }
         catch (e) {
@@ -961,6 +979,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         width: z.number().int().positive().optional().describe('Viewport width for auto-connected sessions.'),
         height: z.number().int().positive().optional().describe('Viewport height for auto-connected sessions.'),
         slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
+        stealth: stealthInput(),
         formId: z.string().optional().describe('Optional form id from geometra_form_schema or geometra_page_model'),
         valuesById: formValuesRecordSchema.optional().describe('Form values keyed by stable field id from geometra_form_schema'),
         valuesByLabel: formValuesRecordSchema.optional().describe('Form values keyed by schema field label'),
@@ -998,7 +1017,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
             .describe('When auto-connecting via pageUrl/url, request an isolated proxy (own brand-new Chromium, destroyed on disconnect). Required for safe parallel form submission. See geometra_connect for details. Ignored when reusing an existing sessionId — set isolated on the original geometra_connect for that case.'),
         detail: detailInput(),
         sessionId: sessionIdInput,
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, resumeFromIndex, verifyFills, skipPreFilled, isolated, detail, sessionId }) => {
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, resumeFromIndex, verifyFills, skipPreFilled, isolated, detail, sessionId }) => {
         const directFields = !includeSteps && !formId && Object.keys(valuesById ?? {}).length === 0
             ? directLabelBatchFields(valuesByLabel)
             : null;
@@ -1011,6 +1030,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
             width,
             height,
             slowMo,
+            stealth,
             isolated,
             awaitInitialFrame: directFields ? false : undefined,
         }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_fill_form.');
@@ -1270,6 +1290,7 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         width: z.number().int().positive().optional().describe('Viewport width for auto-connected sessions.'),
         height: z.number().int().positive().optional().describe('Viewport height for auto-connected sessions.'),
         slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
+        stealth: stealthInput(),
         isolated: z.boolean().optional().default(false).describe('When auto-connecting via pageUrl/url, request an isolated proxy. Required for safe parallel form submission.'),
         formId: z.string().optional().describe('Optional form id from geometra_form_schema or geometra_page_model'),
         valuesById: formValuesRecordSchema.optional().describe('Form values keyed by stable field id from geometra_form_schema'),
@@ -1283,11 +1304,11 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         failOnInvalid: z.boolean().optional().default(false).describe('Return an error if invalid fields remain after the submit wait resolves.'),
         detail: detailInput(),
         sessionId: sessionIdInput,
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, isolated, formId, valuesById, valuesByLabel, submit, submitIndex, submitTimeoutMs, waitFor, skipFill, softTimeoutMs, failOnInvalid, detail, sessionId }) => {
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, isolated, formId, valuesById, valuesByLabel, submit, submitIndex, submitTimeoutMs, waitFor, skipFill, softTimeoutMs, failOnInvalid, detail, sessionId }) => {
         const toolStartedAt = performance.now();
         const effectiveSoftTimeoutMs = softTimeoutMs ?? HOST_SAFE_TOOL_TIMEOUT_MS;
         const deadlineAt = toolStartedAt + effectiveSoftTimeoutMs;
-        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_submit_form.');
+        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, stealth, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_submit_form.');
         if (!resolved.ok)
             return err(resolved.error);
         const session = resolved.session;
@@ -1572,6 +1593,7 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         width: z.number().int().positive().optional().describe('Viewport width for auto-connected sessions.'),
         height: z.number().int().positive().optional().describe('Viewport height for auto-connected sessions.'),
         slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
+        stealth: stealthInput(),
         isolated: z
             .boolean()
             .optional()
@@ -1595,7 +1617,7 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         output: z.enum(['full', 'final']).optional().default('full').describe('`full` (default) returns counts and optional step listings. `final` keeps only completion state plus final semantic signals.'),
         detail: detailInput(),
         sessionId: sessionIdInput,
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, isolated, actions, resumeFromIndex, softTimeoutMs, stopOnError, includeSteps, output, detail, sessionId }) => {
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, isolated, actions, resumeFromIndex, softTimeoutMs, stopOnError, includeSteps, output, detail, sessionId }) => {
         const toolStartedAt = performance.now();
         const effectiveSoftTimeoutMs = softTimeoutMs ?? HOST_SAFE_TOOL_TIMEOUT_MS;
         const deadlineAt = toolStartedAt + effectiveSoftTimeoutMs;
@@ -1608,6 +1630,7 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
             width,
             height,
             slowMo,
+            stealth,
             isolated,
             awaitInitialFrame: canDeferInitialFrameForRunActions(actions) ? false : undefined,
         }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_run_actions.');
@@ -1800,6 +1823,7 @@ Unlike geometra_expand_section, this collapses repeated radio/button groups into
         width: z.number().int().positive().optional().describe('Viewport width for auto-connected sessions.'),
         height: z.number().int().positive().optional().describe('Viewport height for auto-connected sessions.'),
         slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
+        stealth: stealthInput(),
         isolated: z
             .boolean()
             .optional()
@@ -1814,8 +1838,8 @@ Unlike geometra_expand_section, this collapses repeated radio/button groups into
         sinceSchemaId: z.string().optional().describe('If the current schema matches this id, return changed=false without resending forms'),
         format: formSchemaFormatInput(),
         sessionId: sessionIdInput,
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, isolated, formId, maxFields, onlyRequiredFields, onlyInvalidFields, includeOptions, includeContext, sinceSchemaId, format, sessionId }) => {
-        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_form_schema.');
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, isolated, formId, maxFields, onlyRequiredFields, onlyInvalidFields, includeOptions, includeContext, sinceSchemaId, format, sessionId }) => {
+        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, stealth, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_form_schema.');
         if (!resolved.ok)
             return err(resolved.error);
         const session = resolved.session;
@@ -2852,6 +2876,7 @@ async function ensureToolSession(target, missingConnectionMessage = 'Not connect
                 width: target.width,
                 height: target.height,
                 slowMo: target.slowMo,
+                ...(target.stealth !== undefined && { stealth: target.stealth }),
                 awaitInitialFrame: target.awaitInitialFrame,
                 isolated: target.isolated,
             });

package/dist/session.d.ts

@@ -488,6 +488,7 @@ export declare function prewarmProxy(options: {
     pageUrl: string;
     port?: number;
     headless?: boolean;
+    stealth?: boolean;
     width?: number;
     height?: number;
     slowMo?: number;
@@ -499,6 +500,7 @@ export declare function prewarmProxy(options: {
     pageUrl: string;
     wsUrl: string;
     headless: boolean;
+    stealth: boolean;
     width: number;
     height: number;
 }>;
@@ -524,6 +526,7 @@ export declare function connectThroughProxy(options: {
     width?: number;
     height?: number;
     slowMo?: number;
+    stealth?: boolean;
     awaitInitialFrame?: boolean;
     eagerInitialExtract?: boolean;
     /**

package/dist/session.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
 import WebSocket from 'ws';
-import { spawnGeometraProxy, startEmbeddedGeometraProxy } from './proxy-spawn.js';
+import { resolveStealthMode, spawnGeometraProxy, startEmbeddedGeometraProxy, } from './proxy-spawn.js';
 import { completeSessionLifecycle, failSessionLifecycle, heartbeatSessionLifecycle, initializeSessionLifecycle, recordSessionSnapshot, } from './session-state.js';
 /**
  * Stable identity for an outbound proxy config, used as the reusable-pool
@@ -143,10 +143,12 @@ function setReusableProxy(proxy, wsUrl, opts) {
     clearReusableProxiesIfExited();
     const now = Date.now();
     const proxyKey = proxyKeyFor(opts.proxy);
+    const stealth = resolveStealthMode(opts.stealth);
     const existing = reusableProxies.find(entry => sameReusableProxyEntry(entry, proxy));
     if (existing) {
         existing.wsUrl = wsUrl;
-        existing.headless = opts.headless === true;
+        existing.headless = opts.headless !== false;
+        existing.stealth = stealth;
         existing.slowMo = opts.slowMo ?? 0;
         existing.width = opts.width ?? 1280;
         existing.height = opts.height ?? 720;
@@ -161,7 +163,8 @@ function setReusableProxy(proxy, wsUrl, opts) {
         const entry = {
             child,
             wsUrl,
-            headless: opts.headless === true,
+            headless: opts.headless !== false,
+            stealth,
             slowMo: opts.slowMo ?? 0,
             width: opts.width ?? 1280,
             height: opts.height ?? 720,
@@ -187,7 +190,8 @@ function setReusableProxy(proxy, wsUrl, opts) {
     reusableProxies.push({
         runtime: proxy.runtime,
         wsUrl,
-        headless: opts.headless === true,
+        headless: opts.headless !== false,
+        stealth,
         slowMo: opts.slowMo ?? 0,
         width: opts.width ?? 1280,
         height: opts.height ?? 720,
@@ -320,6 +324,11 @@ function evictOldestSession() {
 function formatUnknownError(err) {
     return err instanceof Error ? err.message : String(err);
 }
+function rejectOnRuntimeReadyFailure(runtime) {
+    return new Promise((_, reject) => {
+        runtime.ready.catch(reject);
+    });
+}
 function warnSessionLifecycleError(action, session, err) {
     console.warn(`geometra-mcp: failed to ${action} for session ${session.id}: ${formatUnknownError(err)}`);
 }
@@ -404,7 +413,8 @@ function stopSessionHeartbeat(session) {
 }
 function reusableProxyMatchesOptions(entry, options) {
     return (entry.pageUrl === options.pageUrl &&
-        entry.headless === (options.headless === true) &&
+        entry.headless === (options.headless !== false) &&
+        entry.stealth === resolveStealthMode(options.stealth) &&
         entry.slowMo === (options.slowMo ?? 0) &&
         entry.width === (options.width ?? 1280) &&
         entry.height === (options.height ?? 720) &&
@@ -421,13 +431,15 @@ function findExactReusableProxy(options) {
 }
 function findReusableProxy(options) {
     clearReusableProxiesIfExited();
-    const desiredHeadless = options.headless === true;
+    const desiredHeadless = options.headless !== false;
+    const desiredStealth = resolveStealthMode(options.stealth);
     const desiredSlowMo = options.slowMo ?? 0;
     const desiredWidth = options.width ?? 1280;
     const desiredHeight = options.height ?? 720;
     const desiredProxyKey = proxyKeyFor(options.proxy);
     return reusableProxies
         .filter(entry => entry.headless === desiredHeadless
+        && entry.stealth === desiredStealth
         && entry.slowMo === desiredSlowMo
         // Proxy partition is hard — a session with residential proxy MUST NOT
         // attach to a pooled direct-connection Chromium (and vice versa).
@@ -458,7 +470,8 @@ export async function prewarmProxy(options) {
             transport: existing.runtime ? 'embedded' : 'child',
             pageUrl: options.pageUrl,
             wsUrl: existing.wsUrl,
-            headless: options.headless === true,
+            headless: options.headless !== false,
+            stealth: resolveStealthMode(options.stealth),
             width: options.width ?? 1280,
             height: options.height ?? 720,
         };
@@ -472,6 +485,7 @@ export async function prewarmProxy(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             proxy: options.proxy,
         });
         try {
@@ -484,6 +498,7 @@ export async function prewarmProxy(options) {
         setReusableProxy({ runtime }, wsUrl, {
             headless: options.headless,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             width: options.width,
             height: options.height,
             pageUrl: options.pageUrl,
@@ -496,7 +511,8 @@ export async function prewarmProxy(options) {
             transport: 'embedded',
             pageUrl: options.pageUrl,
             wsUrl,
-            headless: options.headless === true,
+            headless: options.headless !== false,
+            stealth: resolveStealthMode(options.stealth),
             width: options.width ?? 1280,
             height: options.height ?? 720,
         };
@@ -512,11 +528,13 @@ export async function prewarmProxy(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             proxy: options.proxy,
         });
         setReusableProxy({ child }, wsUrl, {
             headless: options.headless,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             width: options.width,
             height: options.height,
             pageUrl: options.pageUrl,
@@ -528,7 +546,8 @@ export async function prewarmProxy(options) {
             transport: 'child',
             pageUrl: options.pageUrl,
             wsUrl,
-            headless: options.headless === true,
+            headless: options.headless !== false,
+            stealth: resolveStealthMode(options.stealth),
             width: options.width ?? 1280,
             height: options.height ?? 720,
         };
@@ -621,16 +640,20 @@ async function startFreshProxySession(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             eagerInitialExtract,
             proxy: options.proxy,
         });
         pendingEmbeddedRuntime = runtime;
         const proxyStartMs = performance.now() - proxyStartStartedAt;
-        const session = await connect(wsUrl, {
-            skipInitialResize: true,
-            closePreviousProxy: false,
-            awaitInitialFrame: options.awaitInitialFrame,
-        });
+        const session = await Promise.race([
+            connect(wsUrl, {
+                skipInitialResize: true,
+                closePreviousProxy: false,
+                awaitInitialFrame: options.awaitInitialFrame,
+            }),
+            rejectOnRuntimeReadyFailure(runtime),
+        ]);
         // Connect succeeded — the session now owns the runtime, so the
         // catch-block cleanup below must not also close it.
         pendingEmbeddedRuntime = undefined;
@@ -649,6 +672,7 @@ async function startFreshProxySession(options) {
             setReusableProxy({ runtime }, wsUrl, {
                 headless: options.headless,
                 slowMo: options.slowMo,
+                stealth: options.stealth,
                 width: options.width,
                 height: options.height,
                 pageUrl: options.pageUrl,
@@ -695,6 +719,7 @@ async function startFreshProxySession(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             eagerInitialExtract,
             proxy: options.proxy,
         });
@@ -717,6 +742,7 @@ async function startFreshProxySession(options) {
                 setReusableProxy({ child }, wsUrl, {
                     headless: options.headless,
                     slowMo: options.slowMo,
+                    stealth: options.stealth,
                     width: options.width,
                     height: options.height,
                     pageUrl: options.pageUrl,

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.61.2",
+  "version": "1.62.1",
   "description": "MCP server for Geometra — interact with running Geometra apps via the geometry protocol, no browser needed",
   "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://github.com/razroo/geometra",
+    "url": "https://github.com/Agent-Pattern-Labs/geometra",
     "directory": "mcp"
   },
   "bin": {
@@ -32,7 +32,7 @@
     "ui-testing"
   ],
   "dependencies": {
-    "@geometra/proxy": "^1.61.2",
+    "@geometra/proxy": "^1.62.1",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@razroo/parallel-mcp": "^0.1.0",
     "ws": "^8.18.0",