@debugg-ai/debugg-ai-mcp 6.1.6 → 6.2.2

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Local browser runs are headless by default (check_app_in_browser, probe_page, profile path). `headless: false` is opt-in and now launches minimized and off-screen without taking focus.
+
+### Changed — local browser is the free default; cloud browsers are the paid option
+- `check_app_in_browser`: leave `browser` unset and it uses your own Chrome when one is installed (stdio server), else the cloud browser; `browser: "local"` or `"remote"` still force one. `DEBUGGAI_LOCAL_BROWSER` is gone: asking for `browser: "local"` is the consent, and the allowlist, sealed credentials and MCP-owned profile are unchanged. It is refused on the hosted HTTP server (no machine of yours). On a backend without local executors an unset `browser` falls back to the cloud browser.
+- A plan without cloud browsers gets a structured `PLAN_REQUIRED` error (HTTP 402) with the message, upgrade link, docs link and how to run in your own Chrome, shown as-is and never retried or silently switched. `probe_page` keeps `browser` defaulting to remote.
+
+## [6.2.1] — 2026-11-13
+
+> 6.2.0 was never published; this is its first release. Local click-through needs a backend with local executors enabled (platform flag `EXECUTORS_LOCAL_ENABLED`) and `DEBUGGAI_LOCAL_BROWSER=1` on the MCP server. Without both, nothing changes for existing calls.
+
+### Added — check_app_in_browser on your local Chrome, cloud brain (`browser: "local"`) (epic m7un)
+- New `browser: "local"` (also `headless`, `useProfile`, `allowedDomains`) runs the check in Chrome on your machine while the cloud brain decides each step. The laptop dials out, so no tunnel is needed for localhost or private apps. Opt-in: set `DEBUGGAI_LOCAL_BROWSER=1` in the MCP server environment; stdio only (not the remote HTTP/OAuth server). The platform side is flag-gated, so it needs a backend that has local executors enabled.
+- Uses the sense/think/act brain (`flow/tools/browse`; `DEBUGGAI_LOCAL_TEMPLATE` overrides the slug). The `browser_use` App Evaluation template cannot drive a local browser and is refused by the backend for local runs.
+- Safety: every navigation hop (redirects included) is checked against an allowlist of the target host plus `allowedDomains`/`extraOrigins`; an empty allowlist is refused. Passwords you pass are never sent to the cloud: the brain sees `{{cred:label}}` and the MCP substitutes it locally. Stored environment credentials arrive sealed to a per-session public key and are opened only on your machine. No cookies, HAR or login state are uploaded.
+- Screenshots go to the cloud by default (the brain needs them); `DEBUGGAI_LOCAL_SCREENSHOTS=local_only` keeps them on disk and sends a 1x1 placeholder. Full captures are written under `~/.debugg-ai/captures` (0600).
+- `useProfile` uses an MCP-owned Chrome profile (`~/.debugg-ai/chrome-profile`), never your real Chrome, and requires an allowlist. Note: it keeps persistent cookies between runs but not session cookies (Chrome drops them on close), so an app whose login is a session cookie will ask you to sign in again on the next run.
+- Limits are configuration from the server (heartbeat, lease, in-flight concurrency), not hard-coded in the client. Retries are off for local runs (a retry needs a fresh session). `LOG_LEVEL=debug` logs each executor command.
+- Verified against a flag-on backend: a click-through, a credentialed multi-step login with task creation, and cancel mid-run (call returns at once, Chrome closed).
+
 ### Changed — test_suite `run` retired (platform-g3am)
 - The server removed its suite-run route, so `run` only produced a raw HTML 404. It is gone from the tool's actions and description; a call from an older client now returns an `ActionRetired` error naming `results`, `check_app_in_browser` and `trigger_crawl`, without contacting the server.
 

package/README.md

@@ -23,6 +23,18 @@ clear error on the first localhost-URL call, not a silent hang. Public-URL calls
 non-browser tool, and `test_suite {action:"run"}` (which uses its own dedicated tunnel and
 bypasses Caddy entirely) don't need it either way.
 
+## Local Chrome click-through (`browser: "local"`) — free on every plan
+
+`check_app_in_browser` can run the check in Chrome on your own machine while the DebuggAI cloud brain decides each step (no tunnel needed, works for private and localhost apps):
+
+```
+check_app_in_browser  { "url": "http://localhost:4040", "description": "Sign in and add a task", "browser": "local", "username": "me@x.com", "password": "..." }
+```
+
+- **Free on every plan, and the default when Chrome is installed.** Leave `browser` unset and `check_app_in_browser` uses your own Chrome if it finds one (stdio server); otherwise it uses a cloud browser. Passing `browser: "local"` is all the consent it needs: there is no environment variable to set. Cloud browsers through the MCP (`browser: "remote"`) are included in Professional and above; a plan without them gets `PLAN_REQUIRED` (message, upgrade link, docs link, and how to use your own Chrome instead), never a silent switch. Server-run tests are unchanged.
+- Local runs need a backend with local executors enabled; an unset `browser` quietly uses the cloud browser on a backend without them, while `browser: "local"` says so. Not available on the hosted HTTP/OAuth MCP server (no machine of yours to open Chrome on).
+- Every navigation hop must be on the allowlist (the target host plus `allowedDomains`). Passwords you pass stay on your machine: the cloud sees `{{cred:label}}` and the MCP fills the real value locally. Screenshots go to the cloud by default; `DEBUGGAI_LOCAL_SCREENSHOTS=local_only` keeps them local. `useProfile` keeps persistent cookies between runs, not session cookies.
+
 ## Testing a local app (no Tailscale, no port exposure)
 
 Start your app on localhost, then pass the `http://localhost:<port>` URL straight to the tool. The MCP
@@ -49,7 +61,7 @@ Verified 2026-11-10: servers bound to `127.0.0.1` only (IPv4 Caddy gateways on :
 
 ### Local Chrome capture (opt-in)
 
-`probe_page` accepts `browser: "local"` to capture with Chrome on your own machine: no tunnel, no cloud browser, nothing uploaded (screenshots also saved under `~/.debugg-ai/captures`, mode 0600). The server owner must set `DEBUGGAI_LOCAL_BROWSER=1`; Chrome is found automatically or via `DEBUGGAI_CHROME_PATH`; `playwright-core` is an optional dependency. `useProfile: true` uses an MCP-owned persistent profile (`~/.debugg-ai/chrome-profile`, never your everyday Chrome profile): sign in once with `headless: false, loginWindowMs: 120000`, later local probes are logged in. Profile sessions require `allowedDomains` (or the owner's `DEBUGGAI_PROFILE_ALLOWED_DOMAINS`, which overrides it); top-level navigations off the list, redirect hops included, are blocked.
+`probe_page` accepts `browser: "local"` to capture with Chrome on your own machine: no tunnel, no cloud browser, nothing uploaded (screenshots also saved under `~/.debugg-ai/captures`, mode 0600). stdio server only; Chrome is found automatically or via `DEBUGGAI_CHROME_PATH`; `playwright-core` is an optional dependency. Local runs are headless by default and never open a visible window; `headless: false` is opt-in and launches minimized and off-screen without taking focus. `useProfile: true` uses an MCP-owned persistent profile (`~/.debugg-ai/chrome-profile`, never your everyday Chrome profile): sign in once with `headless: false, loginWindowMs: 120000`, later local probes are logged in. Profile sessions require `allowedDomains` (or the owner's `DEBUGGAI_PROFILE_ALLOWED_DOMAINS`, which overrides it); top-level navigations off the list, redirect hops included, are blocked.
 
 Get an API key at [debugg.ai](https://debugg.ai), then add to your MCP client config:
 

package/dist/handlers/localExecutorBridge.js

@@ -0,0 +1,202 @@
+/**
+ * check_app_in_browser with browser:'local' (epic m7un). The cloud workflow runs as
+ * usual but its page calls are served by the Chrome on THIS machine through the
+ * Executor API v1 (sentinal docs/local-executor-api-design.md). This module owns the
+ * MCP side: create the session, hold Chrome, attach + serve commands while the
+ * workflow executes, tear down. The handler only calls prepare / begin / end.
+ */
+import { config } from '../config/index.js';
+import { logger } from '../utils/logger.js';
+import { localBrowserEnabled, LocalBrowserError, LOCAL_UNAVAILABLE_MESSAGE, findChrome, resolveAllowedDomains } from '../services/localBrowser.js';
+import { OpRunner } from '../services/localExecutor/opRunner.js';
+import { runExecutorSession } from '../services/localExecutor/session.js';
+import { HttpExecutorTransport } from '../services/localExecutor/httpTransport.js';
+import { generateSessionKeys } from '../services/localExecutor/credentialBox.js';
+/**
+ * Passwords never go to the cloud for a local run: the workflow gets `{{cred:<label>}}`
+ * and the real value stays here. Environment-stored credentials (credentialId/role)
+ * live in the cloud and are not handled by this path yet.
+ */
+export function localizeCredentials(input) {
+    const secrets = {};
+    const ph = (label, password) => { secrets[label] = password; return `{{cred:${label}}}`; };
+    const out = { ...input };
+    if (input.username && input.password)
+        out.password = ph(input.username, input.password);
+    if (input.loginCredentials) {
+        out.loginCredentials = input.loginCredentials.map((c) => ({ ...c, password: ph(c.label ?? c.username, c.password) }));
+    }
+    if (input.auth?.password && input.auth.username) {
+        out.auth = { ...input.auth, password: ph(input.auth.username, input.auth.password) };
+    }
+    return { input: out, secrets };
+}
+/**
+ * Local runs are a paid feature. The backend answers a plan that does not include them with
+ * HTTP 402 (or a 403 whose code names the plan/entitlement) and a structured body; show its
+ * message, upgrade link and docs link as they are and never retry. Returns undefined for any
+ * other error.
+ */
+export function planRequiredFromError(err, mode = 'local') {
+    const e = err;
+    const status = e?.statusCode ?? e?.response?.status;
+    const raw = (e?.responseData ?? e?.response?.data);
+    const body = (raw && typeof raw.error === 'object' && raw.error ? raw.error : raw);
+    const pick = (...keys) => { for (const k of keys) {
+        const v = body?.[k];
+        if (typeof v === 'string' && v)
+            return v;
+    } return undefined; };
+    const code = pick('code', 'error_code', 'errorCode');
+    const planish = !!code && /plan|entitle|upgrade|subscription|not_included/i.test(code);
+    if (status !== 402 && !(status === 403 && planish))
+        return undefined;
+    const feature = pick('feature');
+    const message = pick('error', 'message', 'detail') ?? (mode === 'remote' ? 'Cloud browsers are not included in your plan.' : 'This run is not included in your plan.');
+    const upgradeUrl = pick('upgrade_url', 'upgradeUrl');
+    const docsUrl = pick('docs_url', 'docsUrl');
+    const required = body?.required_plans ?? body?.requiredPlans;
+    // A plan without cloud browsers can still run in the caller's own Chrome, for free. Say how; never fall back silently.
+    const alternative = mode === 'remote' ? 'Run it free in your own Chrome: install Chrome and call with browser: "local".' : undefined;
+    const hasHint = /browser:\s*["']?local/i.test(message);
+    const text = [message, alternative && !hasHint ? alternative : undefined, upgradeUrl ? `Upgrade: ${upgradeUrl}` : undefined, docsUrl ? `Docs: ${docsUrl}` : undefined].filter(Boolean).join(' ');
+    return new LocalBrowserError(text, 'PLAN_REQUIRED', { upgradeUrl, docsUrl, ...(feature ? { feature } : {}), ...(required ? { requiredPlans: required } : {}), ...(alternative ? { alternative } : {}) });
+}
+/**
+ * Which browser runs this call. An explicit `browser` always wins. Unset: your own Chrome when it is
+ * installed, the server is not the hosted one, or the call asks for something only local can do
+ * (useProfile); otherwise the cloud browser.
+ */
+export function chooseBrowser(input, env) {
+    if (input.browser === 'local')
+        return { mode: 'local', auto: false };
+    if (input.browser === 'remote')
+        return { mode: 'remote', auto: false };
+    if (input.useProfile)
+        return { mode: 'local', auto: false }; // a profile only exists on this machine
+    const hosted = env?.hosted ?? !localBrowserEnabled();
+    const chrome = env?.chrome ?? !!findChrome();
+    return hosted || !chrome ? { mode: 'remote', auto: false } : { mode: 'local', auto: true };
+}
+export function localAllowedDomains(input, startUrl) {
+    const startHost = (() => { try {
+        return new URL(startUrl).hostname;
+    }
+    catch {
+        return '';
+    } })();
+    const extra = (input.extraOrigins ?? []).map((o) => { try {
+        return new URL(/^\d+$/.test(o) ? `http://localhost:${o}` : o).hostname;
+    }
+    catch {
+        return '';
+    } });
+    if (input.useProfile)
+        return resolveAllowedDomains(input.allowedDomains);
+    return [startHost, ...(input.allowedDomains ?? []), ...extra].filter(Boolean);
+}
+export async function prepareLocalRun(args) {
+    const { client, input, startUrl, secrets, signal } = args;
+    if (!localBrowserEnabled()) {
+        throw new LocalBrowserError(LOCAL_UNAVAILABLE_MESSAGE, 'LOCAL_BROWSER_DISABLED');
+    }
+    const allowed = localAllowedDomains(input, startUrl);
+    if (allowed.length === 0) {
+        throw new LocalBrowserError('A profile session needs an allowlist of domains it may visit: pass allowedDomains or have the server owner set DEBUGGAI_PROFILE_ALLOWED_DOMAINS.', 'PROFILE_ALLOWLIST_REQUIRED');
+    }
+    const headless = input.headless !== false;
+    const screenshotsMode = process.env.DEBUGGAI_LOCAL_SCREENSHOTS === 'local_only' ? 'local_only' : 'cloud';
+    // Chrome starts while the session is being created and the workflow queued.
+    // Mutable on purpose: stored credentials are decrypted into it once the session exists.
+    const liveSecrets = { ...secrets };
+    const keys = generateSessionKeys();
+    const runnerP = OpRunner.open({ allowedDomains: allowed, headless, useProfile: !!input.useProfile, secrets: liveSecrets, screenshots: screenshotsMode, signal });
+    runnerP.catch(() => { });
+    let created;
+    try {
+        created = await client.tx.post('api/v1/executors/sessions', {
+            executor: 'local',
+            allowedDomains: allowed,
+            headless,
+            viewport: { w: 1280, h: 800 },
+            capture: { screenshots: screenshotsMode },
+            // Public half only. The private key never leaves this process.
+            executorPublicKey: keys.publicKey,
+            ...(args.projectId ? { projectId: args.projectId } : {}),
+            ...(input.environmentId ? { environmentId: input.environmentId } : {}),
+            ...(input.credentialId ? { credentialId: input.credentialId } : {}),
+            ...(input.credentialRole ? { credentialRole: input.credentialRole } : {}),
+        });
+    }
+    catch (err) {
+        (await runnerP.catch(() => null))?.close();
+        const planErr = planRequiredFromError(err);
+        if (planErr)
+            throw planErr;
+        const status = err?.response?.status ?? err?.statusCode;
+        if (status === 404) {
+            throw new LocalBrowserError('The DebuggAI backend does not offer local browser execution yet (executor API not enabled for this account).', 'LOCAL_EXECUTOR_UNAVAILABLE');
+        }
+        throw err;
+    }
+    const runner = await runnerP;
+    if (created.captureMode === 'cloud' || created.captureMode === 'local_only')
+        runner.setCaptureMode(created.captureMode);
+    if (typeof created.headless === 'boolean' && created.headless !== (headless !== false)) {
+        logger.warn(`Server runs this session with headless=${created.headless}; the local browser was already launched with headless=${headless !== false}.`);
+    }
+    for (const c of created.credentials ?? []) {
+        try {
+            const pw = keys.open(c.sealed, created.sessionId);
+            liveSecrets[c.label] = pw;
+            // The backend names the placeholder after the label OR the username depending on the resolution path; accept both.
+            if (c.username && !(c.username in liveSecrets))
+                liveSecrets[c.username] = pw;
+        }
+        catch (err) {
+            logger.warn(`Could not open stored credential "${c.label}" (${err instanceof Error ? err.message : 'decrypt failed'})`);
+        }
+    }
+    const limits = {
+        heartbeat_s: created.limits?.heartbeatS ?? 10,
+        lease_s: created.limits?.leaseS ?? 45,
+        max_inline_bytes: created.limits?.maxInlineBytes ?? 1_000_000,
+        max_batch: created.limits?.maxBatch ?? 1,
+        ...(created.limits?.maxInflight ? { max_inflight: created.limits.maxInflight } : {}),
+    };
+    const transport = new HttpExecutorTransport({
+        baseUrl: config.api.baseUrl,
+        authorization: `${config.api.tokenType === 'bearer' ? 'Bearer' : 'Token'} ${config.api.key}`,
+        sessionId: created.sessionId,
+        secret: created.secret,
+    });
+    runner.setUploader((url, ct, bytes) => transport.upload(url, ct, bytes));
+    const stop = new AbortController();
+    const onAbort = () => stop.abort();
+    signal.addEventListener('abort', onAbort, { once: true });
+    let running;
+    return {
+        sessionId: created.sessionId,
+        begin() {
+            running = runExecutorSession({
+                transport, runner, limits, signal: stop.signal,
+                attach: {
+                    executor_version: 'debugg-ai-mcp',
+                    ops_supported: OpRunner.supportedOps(),
+                    browser: { name: 'chrome', headless },
+                    profile: input.useProfile ? 'mcp_owned' : 'ephemeral',
+                    credential_labels: Object.keys(liveSecrets),
+                },
+            }).catch((err) => { logger.warn(`local executor session failed: ${err instanceof Error ? err.message : err}`); return { ended: 'lease_lost', commandsRun: 0 }; });
+        },
+        async end() {
+            signal.removeEventListener('abort', onAbort);
+            if (!running) {
+                await runner.close();
+                return { ended: 'not_started', commandsRun: 0 };
+            }
+            stop.abort();
+            return running;
+        },
+    };
+}

package/dist/handlers/probePageHandler.js

@@ -291,6 +291,7 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                 const firstTargetUrl = targetContexts[group.indices[0]]?.targetUrl ?? groupTargets[0].url;
                 const contextData = {
                     targetUrl: firstTargetUrl,
+                    browserChoice: 'remote', // cloud-browser run: lets the backend apply the plan gate
                     targets: group.indices.map(i => ({
                         url: targetContexts[i].targetUrl ?? input.targets[i].url,
                         // Send null (not undefined) for optional fields so the field exists

package/dist/handlers/testPageChangesHandler.js

@@ -9,7 +9,7 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { fetchImageAsBase64, imageContentBlock, resourceLinkBlock, artifactResourceLinks } from '../utils/imageUtils.js';
 import { DebuggAIServerClient } from '../services/index.js';
-import { getEvalTemplateSlug } from '../services/workflows.js';
+import { getEvalTemplateSlug, getLocalBrowseTemplateSlug } from '../services/workflows.js';
 import { authorizeExtraOrigins, ExtraOriginError } from '../utils/extraOrigins.js';
 import { refreshPendingArtifacts } from '../utils/artifactGrace.js';
 import { adaptVerdict, credentialSubstitutions, summarizeLogins } from '../services/verdictAdapter.js';
@@ -23,6 +23,8 @@ import { extractLocalhostPort, rewriteLocalhostInText } from '../utils/urlParser
 import { getCachedTemplateUuid, getCachedProjectUuid, invalidateTemplateCache, invalidateProjectCache, } from '../utils/handlerCaches.js';
 import { isTransientWorkflowError, transientReasonTag } from '../utils/transientErrors.js';
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
+import { prepareLocalRun, localizeCredentials, planRequiredFromError, chooseBrowser } from './localExecutorBridge.js';
+import { LocalBrowserError } from '../services/localBrowser.js';
 import { projectRequiredMessage, projectLookupFailedPayload } from '../utils/projectRequired.js';
 const logger = new Logger({ module: 'testPageChangesHandler' });
 // Bead kbxy: bounded retry on known transient backend signatures (Pydantic
@@ -112,6 +114,7 @@ export async function testPageChangesHandler(input, context, progressCallback) {
 }
 async function testPageChangesHandlerInner(input, context, rawProgressCallback) {
     const startTime = Date.now();
+    const originalInput = input; // before local credential placeholders are applied
     logger.toolStart('check_app_in_browser', input);
     // Bead 0bq: wrap the progress callback in a circuit-breaker so a single
     // client-side rejection of a stale progressToken (which would normally
@@ -136,6 +139,16 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         : undefined;
     const client = new DebuggAIServerClient(config.api.key);
     await client.init();
+    // browser:'local': Chrome on this machine does the clicking (no tunnel); passwords stay local.
+    const choice = chooseBrowser(input);
+    const localMode = choice.mode === 'local';
+    let localSecrets = {};
+    if (localMode) {
+        const l = localizeCredentials(input);
+        input = l.input;
+        localSecrets = l.secrets;
+    }
+    let localRun;
     const originalUrl = resolveTargetUrl(input);
     let ctx = buildContext(originalUrl);
     let provision;
@@ -227,14 +240,14 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // is a billed leak, and beats a backend node failing mid-run.
         if (!projectUuid && !namedEnvironmentId && lookupError !== undefined && repoName) {
             // The lookup FAILED — not "no project linked" (platform-y2ob.4).
-            const payload = projectLookupFailedPayload(repoName, lookupError);
+            const payload = projectLookupFailedPayload(repoName, lookupError, false);
             logger.warn(`check_app_in_browser: ${payload.message}`);
             return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
         }
         if (!projectUuid && !namedEnvironmentId) {
             const payload = {
                 error: 'ProjectRequired',
-                message: projectRequiredMessage(repoName),
+                message: projectRequiredMessage(repoName, false),
             };
             logger.warn(`check_app_in_browser: ${payload.message}`);
             return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
@@ -263,7 +276,10 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
                 }
             }
-            if (config.devMode) {
+            if (localMode) {
+                logger.info(`check_app_in_browser: local browser — no tunnel for ${ctx.originalUrl}`);
+            }
+            else if (config.devMode) {
                 // Dev mode: local backend can reach localhost directly — no tunnel needed.
                 logger.info(`check_app_in_browser: dev mode — using localhost URL directly: ${ctx.originalUrl}`);
             }
@@ -375,11 +391,14 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // Cache key = the dispatch slug so the cache key and the lookup can never
         // drift apart (bug clka: the key used to be a decoupled 'app evaluation'
         // literal while the lookup searched a different string).
-        const templateUuid = await getCachedTemplateUuid(getEvalTemplateSlug(), async () => {
-            return client.workflows.findEvaluationTemplate();
+        const templateSlug = localMode ? getLocalBrowseTemplateSlug() : getEvalTemplateSlug();
+        const templateUuid = await getCachedTemplateUuid(templateSlug, async () => {
+            return localMode
+                ? client.workflows.findTemplateBySlug(templateSlug)
+                : client.workflows.findEvaluationTemplate();
         });
         if (!templateUuid) {
-            throw new Error(`App Evaluation workflow template not found (slug "${getEvalTemplateSlug()}").`);
+            throw new Error(`${localMode ? 'Local browse' : 'App Evaluation'} workflow template not found (slug "${templateSlug}").`);
         }
         // --- Build context data (camelCase here — axiosTransport auto-converts to snake_case) ---
         const contextData = {
@@ -395,6 +414,12 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             contextData.projectId = projectUuid;
         }
         contextData.headless = true; // D7: the MCP always runs headless — no opt-out.
+        contextData.browserChoice = localMode ? 'local' : 'remote'; // lets the backend apply the cloud-browser plan gate
+        if (localMode) {
+            localRun = await prepareLocalRun({ client, input, startUrl: originalUrl, secrets: localSecrets, signal: abortController.signal, projectId: projectUuid || undefined });
+            contextData.executorSessionId = localRun.sessionId;
+            contextData.goal = contextData.question; // flow/tools/browse reads `goal`
+        }
         // Bead 56kd.6: forward the auth-precondition deep-link intent verbatim per
         // backend contract sentinal-k8x1f.8 (contextData.auth). Thin relay — express
         // intent + forward; the backend authenticates then navigates to deepUrl. Only
@@ -504,7 +529,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         //   28:    Complete
         const BACKEND_SETUP_END = 6;
         const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
-        const MAX_RETRIES = getMaxTransientRetries();
+        const MAX_RETRIES = localMode ? 0 : getMaxTransientRetries(); // a retry would need a fresh local session
         let executeResponse;
         let executionUuid = '';
         let finalExecution;
@@ -539,6 +564,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             // the target forward; the previous attempt already reached a terminal
             // state, so there is nothing to cancel there).
             currentExecutionUuid = executionUuid;
+            localRun?.begin();
             logger.info(`Execution queued: ${executionUuid}${attempt > 1 ? ` (retry ${attempt - 1}/${MAX_RETRIES})` : ''}`);
             // The abort can fire BEFORE anything is queued — while provisioning the
             // tunnel or resolving the template — and there is no abort check between
@@ -930,6 +956,18 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         return tunnelFault ? { content, isError: true } : { content };
     }
     catch (error) {
+        // Browser was not chosen and this backend has no local executors: use the cloud browser instead.
+        if (choice.auto && error instanceof LocalBrowserError && error.code === 'LOCAL_EXECUTOR_UNAVAILABLE') {
+            logger.info('check_app_in_browser: local executors are not available on this backend; using the cloud browser');
+            return testPageChangesHandlerInner({ ...originalInput, browser: 'remote' }, context, rawProgressCallback);
+        }
+        const planErr = planRequiredFromError(error, localMode ? 'local' : 'remote');
+        if (error instanceof LocalBrowserError || planErr) {
+            const lbe = (planErr ?? error);
+            const payload = { error: lbe.code, message: lbe.message, ...(lbe.details ?? {}) };
+            logger.warn(`check_app_in_browser (local): ${lbe.code}: ${lbe.message}`);
+            return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+        }
         const duration = Date.now() - startTime;
         logger.toolError('check_app_in_browser', error, duration);
         if (error instanceof Error && (error.message.includes('not found') || error.message.includes('401'))) {
@@ -939,6 +977,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         throw handleExternalServiceError(error, 'DebuggAI', 'test execution');
     }
     finally {
+        await localRun?.end().catch(() => { });
         if (requestSignal)
             requestSignal.removeEventListener('abort', onAbort);
         // §2.4: release this call's claim on the shared port route (no-op if we

package/dist/services/localBrowser.js

@@ -6,7 +6,8 @@
  * Everything stays local: screenshots are returned inline and also written under
  * ~/.debugg-ai/captures (0600).
  *
- * Opt-in at the server: DEBUGGAI_LOCAL_BROWSER=1. With `useProfile`, the browser
+ * No server opt-in: asking for `browser: "local"` in the call is the consent (the allowlist stays
+ * required). It is unavailable on the hosted HTTP server, which has no machine of yours. With `useProfile`, the browser
  * uses an MCP-owned persistent profile (~/.debugg-ai/chrome-profile, override with
  * DEBUGGAI_CHROME_PROFILE_DIR) the user logs into once via `loginToLocalProfile`;
  * the user's everyday Chrome profile is never touched.
@@ -14,11 +15,14 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { installNavigationGuard, isLoopbackHost } from './navigationGuard.js';
 export class LocalBrowserError extends Error {
     code;
-    constructor(message, code) {
+    details;
+    constructor(message, code, details) {
         super(message);
         this.code = code;
+        this.details = details;
         this.name = 'LocalBrowserError';
     }
 }
@@ -39,9 +43,11 @@ export function resolveAllowedDomains(perCall, env = process.env) {
     const owner = (env.DEBUGGAI_PROFILE_ALLOWED_DOMAINS ?? '').split(',').map((s) => s.trim()).filter(Boolean);
     return owner.length > 0 ? owner : (perCall ?? []).filter(Boolean);
 }
+/** Local Chrome needs a machine of the caller's: it is available on stdio, never on the hosted HTTP server. */
 export function localBrowserEnabled(env = process.env) {
-    return env.DEBUGGAI_LOCAL_BROWSER === '1' || env.DEBUGGAI_LOCAL_BROWSER === 'true';
+    return (env.DEBUGGAI_MCP_TRANSPORT || 'stdio').toLowerCase() !== 'http';
 }
+export const LOCAL_UNAVAILABLE_MESSAGE = 'Local browser runs are not available on the hosted (HTTP) MCP server: there is no machine of yours to open Chrome on. Use browser "remote", or run the MCP on your own machine (stdio).';
 export function debuggHome(env = process.env) {
     return env.DEBUGGAI_HOME || path.join(os.homedir(), '.debugg-ai');
 }
@@ -70,21 +76,15 @@ async function loadPlaywright() {
         throw new LocalBrowserError('Local browser mode needs the optional dependency playwright-core, which is not installed. Run `npm i playwright-core` next to the MCP.', 'PLAYWRIGHT_MISSING');
     }
 }
-function safeHost(u) {
-    try {
-        return new URL(u).hostname;
-    }
-    catch {
-        return u;
-    }
-}
-function ensurePrivateDir(dir) {
+export function ensurePrivateDir(dir) {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
 }
-async function launch(opts) {
+/** Headed runs are opt-in; even then keep the window out of the way: off-screen, minimized, no focus grab. */
+export const HEADED_QUIET_ARGS = ['--start-minimized', '--window-position=-32000,-32000', '--no-first-run', '--no-default-browser-check'];
+export async function launch(opts) {
     const pw = await loadPlaywright();
     const executablePath = findChrome();
-    const base = { headless: opts.headless, ...(executablePath ? { executablePath } : { channel: 'chrome' }) };
+    const base = { headless: opts.headless, ...(opts.headless ? {} : { args: HEADED_QUIET_ARGS }), ...(executablePath ? { executablePath } : { channel: 'chrome' }) };
     try {
         if (opts.useProfile) {
             const dir = profileDir();
@@ -127,7 +127,7 @@ function summarize(entries) {
 }
 export async function localCapture(o) {
     if (!localBrowserEnabled()) {
-        throw new LocalBrowserError('Local browser mode is off. Set DEBUGGAI_LOCAL_BROWSER=1 in the MCP server environment to allow it.', 'LOCAL_BROWSER_DISABLED');
+        throw new LocalBrowserError(LOCAL_UNAVAILABLE_MESSAGE, 'LOCAL_BROWSER_DISABLED');
     }
     const allowed = o.useProfile ? resolveAllowedDomains(o.allowedDomains) : [];
     if (o.useProfile && allowed.length === 0) {
@@ -139,71 +139,19 @@ export async function localCapture(o) {
     o.signal?.addEventListener('abort', onAbort, { once: true });
     try {
         const page = context.pages()[0] ?? await context.newPage();
+        const blocked = [];
         if (o.useProfile) {
-            const isLocal = (h) => ['localhost', '127.0.0.1', '[::1]', '::1'].includes(h);
             const startHost = (() => { try {
                 return new URL(o.url).hostname;
             }
             catch {
                 return '';
             } })();
-            if (!hostAllowed(startHost, allowed) && !isLocal(startHost)) {
+            if (!hostAllowed(startHost, allowed) && !isLoopbackHost(startHost)) {
                 throw new LocalBrowserError(`${startHost || o.url} is not in the allowlist for this profile session.`, 'DOMAIN_NOT_ALLOWED');
             }
-            // Block top-level DOCUMENT loads off the allowlist, redirect hops included, via
-            // CDP Fetch (Playwright's route() never sees server-side redirect hops, so it
-            // cannot enforce this). Sub-resources (CDNs) pass.
-            const guard = async (pg) => {
-                const cdp = await context.newCDPSession(pg);
-                const mainFrameId = (await cdp.send('Page.getFrameTree')).frameTree.frame.id;
-                await cdp.send('Fetch.enable', { patterns: [
-                        { urlPattern: '*', resourceType: 'Document', requestStage: 'Request' },
-                        { urlPattern: '*', resourceType: 'Document', requestStage: 'Response' },
-                    ] });
-                cdp.on('Fetch.requestPaused', (ev) => {
-                    void (async () => {
-                        const check = (u) => {
-                            try {
-                                const h = new URL(u).hostname;
-                                return hostAllowed(h, allowed) || isLocal(h);
-                            }
-                            catch {
-                                return false;
-                            }
-                        };
-                        try {
-                            if (ev.frameId !== mainFrameId) {
-                                await cdp.send(ev.responseStatusCode ? 'Fetch.continueResponse' : 'Fetch.continueRequest', { requestId: ev.requestId });
-                                return;
-                            }
-                            if (ev.responseStatusCode === undefined) {
-                                if (!check(ev.request.url)) {
-                                    blocked.push(safeHost(ev.request.url));
-                                    await cdp.send('Fetch.failRequest', { requestId: ev.requestId, errorReason: 'BlockedByClient' });
-                                    return;
-                                }
-                                await cdp.send('Fetch.continueRequest', { requestId: ev.requestId });
-                                return;
-                            }
-                            const loc = ev.responseHeaders?.find((h) => h.name.toLowerCase() === 'location')?.value;
-                            if (ev.responseStatusCode >= 300 && ev.responseStatusCode < 400 && loc) {
-                                const next = new URL(loc, ev.request.url).toString();
-                                if (!check(next)) {
-                                    blocked.push(safeHost(next));
-                                    await cdp.send('Fetch.failRequest', { requestId: ev.requestId, errorReason: 'BlockedByClient' });
-                                    return;
-                                }
-                            }
-                            await cdp.send('Fetch.continueResponse', { requestId: ev.requestId });
-                        }
-                        catch { /* page closed */ }
-                    })();
-                });
-            };
-            await guard(page);
-            context.on('page', (pg) => { void guard(pg).catch(() => { }); });
+            await installNavigationGuard(context, allowed, (h) => blocked.push(h));
         }
-        const blocked = [];
         const consoleErrors = [];
         const net = [];
         page.on('console', (m) => { if (m.type() === 'error' || m.type() === 'warning')

package/dist/services/localExecutor/credentialBox.js

@@ -0,0 +1,43 @@
+/**
+ * Sealed-box credential delivery. The executor makes a fresh X25519 keypair per session
+ * and sends ONLY the public key at session creation. The server decrypts a stored
+ * credential with its own key (which never leaves the server), then re-encrypts it to
+ * this public key before it enters any queue or response. Only this process can open it.
+ *
+ * Envelope (JSON, all base64): { v:1, alg:'x25519-hkdf-sha256-aes256gcm', epk, iv, ct, tag }
+ *   epk = sender's ephemeral X25519 public key, SPKI DER
+ *   key = HKDF-SHA256(ikm = ECDH(epk, recipient private), salt = empty, info = 'debuggai-executor-credential-v1', 32 bytes)
+ *   ct/tag = AES-256-GCM(key, iv(12 bytes), plaintext); AAD = the session id
+ */
+import crypto from 'node:crypto';
+export const SEAL_ALG = 'x25519-hkdf-sha256-aes256gcm';
+export const SEAL_INFO = 'debuggai-executor-credential-v1';
+export function generateSessionKeys() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
+    return {
+        publicKey: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+        open(env, sessionId) {
+            if (env.v !== 1 || env.alg !== SEAL_ALG)
+                throw new Error(`Unsupported credential envelope (${env.alg}).`);
+            const epk = crypto.createPublicKey({ key: Buffer.from(env.epk, 'base64'), type: 'spki', format: 'der' });
+            const shared = crypto.diffieHellman({ privateKey, publicKey: epk });
+            const key = Buffer.from(crypto.hkdfSync('sha256', shared, Buffer.alloc(0), SEAL_INFO, 32));
+            const d = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(env.iv, 'base64'));
+            d.setAAD(Buffer.from(sessionId));
+            d.setAuthTag(Buffer.from(env.tag, 'base64'));
+            return Buffer.concat([d.update(Buffer.from(env.ct, 'base64')), d.final()]).toString('utf8');
+        },
+    };
+}
+/** Reference sealer (server side lives in the platform repo; used here for tests and as the spec). */
+export function sealTo(publicKeyB64, plaintext, sessionId) {
+    const recipient = crypto.createPublicKey({ key: Buffer.from(publicKeyB64, 'base64'), type: 'spki', format: 'der' });
+    const eph = crypto.generateKeyPairSync('x25519');
+    const shared = crypto.diffieHellman({ privateKey: eph.privateKey, publicKey: recipient });
+    const key = Buffer.from(crypto.hkdfSync('sha256', shared, Buffer.alloc(0), SEAL_INFO, 32));
+    const iv = crypto.randomBytes(12);
+    const c = crypto.createCipheriv('aes-256-gcm', key, iv);
+    c.setAAD(Buffer.from(sessionId));
+    const ct = Buffer.concat([c.update(plaintext, 'utf8'), c.final()]);
+    return { v: 1, alg: SEAL_ALG, epk: eph.publicKey.export({ type: 'spki', format: 'der' }).toString('base64'), iv: iv.toString('base64'), ct: ct.toString('base64'), tag: c.getAuthTag().toString('base64') };
+}