e2e 0.17.0 → 0.18.0

package/README.md

@@ -7,6 +7,10 @@
   <a href="https://tester.army/discord"><img alt="Join the community on Discord" src="https://img.shields.io/badge/Join%20the%20community-5865F2.svg?style=for-the-badge&logo=discord&logoColor=white&labelColor=000000" /></a>
 </p>
 
+<p align="center">
+  <a href="https://www.star-history.com/tester-army/e2e"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=tester-army/e2e&type=trending&theme=dark" /><img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=tester-army/e2e&type=trending" /></picture></a>
+</p>
+
 # e2e
 
 [e2e](https://tester.army/e2e?utm_source=e2e&utm_medium=github&utm_campaign=readme_intro) is an end-to-end testing framework for web and mobile apps. Describe a goal in natural language and an agent drives the app to reach it. Check the result with locators and assertions in the same test.
@@ -40,6 +44,11 @@ npx e2e init
 config and an example test. The
 [quickstart](https://e2e.tester.army/docs/quickstart) covers the rest.
 
+To see a finished setup in your stack, open
+[`examples/`](https://github.com/tester-army/e2e/tree/main/examples):
+Vite, Next.js, Expo, and SwiftUI, each a standalone project with a passing
+suite.
+
 ## Packages
 
 | Package | What it does |
@@ -50,6 +59,7 @@ config and an example test. The
 | [`@e2e-dev/github`](https://www.npmjs.com/package/@e2e-dev/github) | Reporter that posts results as a pull request comment. |
 | [`@e2e-dev/kernel`](https://www.npmjs.com/package/@e2e-dev/kernel) | Kernel hosted browsers for the web engine. |
 | [`@e2e-dev/eas`](https://www.npmjs.com/package/@e2e-dev/eas) | EAS Simulators hosted iOS simulators and Android emulators for the mobile engine. |
+| [`@e2e-dev/decision`](https://e2e.tester.army/docs/decision-models) | Decision-model executors for bounded semantic actions and assertions. |
 
 ## Documentation
 

package/dist/.build.json

@@ -1 +1 @@
-{"version":"0.17.0"}
+{"version":"0.18.0"}

package/dist/agent/ai-sdk.js

@@ -23,10 +23,11 @@ export function asSdkLanguageModel(instance) {
 }
 /**
  * The cache lives on `globalThis`, not in module state: config and test
- * modules load in an isolated tsx realm, so an executor constructed in config
- * code and the runner's own model plumbing would otherwise hold two separate
- * caches — and two separate `ai` module instances whose error classes fail
- * each other's instanceof checks. One slot, one SDK instance, every realm.
+ * modules may import a copy of e2e other than the runner's, so an executor
+ * constructed in config code and the runner's own model plumbing would
+ * otherwise hold two separate caches, and two separate `ai` module instances
+ * whose error classes fail each other's instanceof checks. One slot, one SDK
+ * instance, every copy.
  */
 const cacheSlot = realmSlot('e2e.ai-sdk.v1');
 function cache() {

package/dist/agent/error.js

@@ -1,5 +1,5 @@
 /** Runner-owned agent error classification. */
-import { classifyError, E2EError } from '../internal/errors.js';
+import { classifyError, E2EError, isE2EError } from '../internal/errors.js';
 /**
  * The single source of truth for the closed agent code set: exit/result class
  * for every code, the blocked category for codes a `blocked` verdict may
@@ -55,7 +55,7 @@ const MODEL_UNREACHABLE_CODES = new Set(Object.entries(AGENT_CODE_TABLE)
  * model was shown may be what went wrong.
  */
 export function isModelUnreachable(error) {
-    if (!(error instanceof E2EError) && !isAgentError(error))
+    if (!isE2EError(error))
         return false;
     return MODEL_UNREACHABLE_CODES.has(error.code);
 }
@@ -95,7 +95,7 @@ const AGENT_CODES = new Set(Object.keys(CATEGORY_BY_CODE));
 export function toAgentError(cause) {
     if (isAgentError(cause))
         return cause;
-    const classified = cause instanceof E2EError ? cause : classifyError(cause);
+    const classified = classifyError(cause);
     if (AGENT_CODES.has(classified.code)) {
         return new AgentError(classified.code, classified.message, { cause });
     }

package/dist/agent/invocation.js

@@ -104,14 +104,13 @@ export class Invocation {
     /** Captures one raw observation through the shared race-hardened path. */
     captureObservation(pixels) {
         return retryingObserve({
-            observe: (operation) => this.session.observe(operation, {
-                pixels,
-                pixelFallback: this.options.vision !== false && !this.runtime.exposure.withholdsPixels,
-            }),
+            observe: (operation, pixelFallback) => this.session.observe(operation, { pixels, pixelFallback }),
             operation: () => this.operation(),
             guard: (cause) => this.checkDeadline(cause),
             signal: this.runtime.engine.signal,
             api: this.options.api,
+            fallback: this.options.vision !== false,
+            tainted: () => this.runtime.exposure.withholdsPixels,
         });
     }
     /**

package/dist/agent/model/tool-choice.d.ts

@@ -33,6 +33,15 @@ export declare function isForcedToolChoiceDowngraded(warning: {
 export declare function isForcedToolCallSkipped(error: unknown): error is {
     readonly content?: readonly unknown[];
 };
+/**
+ * Whether a turn forced to call `complete_step` called other tools only. The
+ * AI SDK throws `AI_ToolChoiceViolationError` for that too, with the reply's
+ * raw content; it is the model breaking the protocol, as when it names a tool
+ * the turn does not offer, not the provider failing.
+ */
+export declare function isForcedToolCallMismatched(error: unknown): error is {
+    readonly content: readonly unknown[];
+};
 /**
  * Whether a provider failure says the model does not accept a forced tool
  * choice. Reads the message and the raw response body of the error and of

package/dist/agent/model/tool-choice.js

@@ -42,6 +42,20 @@ export function isForcedToolCallSkipped(error) {
     const record = error;
     return record.name === 'AI_ToolChoiceViolationError' && record.finishReason === 'stop';
 }
+/**
+ * Whether a turn forced to call `complete_step` called other tools only. The
+ * AI SDK throws `AI_ToolChoiceViolationError` for that too, with the reply's
+ * raw content; it is the model breaking the protocol, as when it names a tool
+ * the turn does not offer, not the provider failing.
+ */
+export function isForcedToolCallMismatched(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const record = error;
+    return (record.name === 'AI_ToolChoiceViolationError' &&
+        Array.isArray(record.content) &&
+        record.content.some((part) => typeof part === 'object' && part !== null && 'type' in part && part.type === 'tool-call'));
+}
 /** Longest cause chain walked; a wrapped error rarely nests deeper. */
 const MAX_CAUSE_DEPTH = 8;
 /**

package/dist/agent/observation-feed.js

@@ -306,14 +306,13 @@ export class ObservationFeed {
     async capture(pixels) {
         this.opening = undefined;
         const raw = await retryingObserve({
-            observe: (operation) => this.runtime.engine.session.observe(operation, {
-                pixels,
-                pixelFallback: !this.runtime.exposure.withholdsPixels,
-            }),
+            observe: (operation, pixelFallback) => this.runtime.engine.session.observe(operation, { pixels, pixelFallback }),
             operation: () => this.accounting.operation(),
             guard: (cause) => this.accounting.checkpoint(cause),
             signal: this.runtime.engine.signal,
             api: this.accounting.api,
+            fallback: true,
+            tainted: () => this.runtime.exposure.withholdsPixels,
         });
         if (raw.kind === 'pixels') {
             this.semanticHistory = false;

package/dist/agent/phases.d.ts

@@ -67,11 +67,17 @@ export declare function checkStepClock(options: {
  * re-read rather than surfaced as a failed call. `guard` is the caller's
  * clock check, so a capture that outlives the deadline reports the step's own
  * timeout rather than whichever transport error the truncated budget produced.
+ * `fallback` asks the engine for fallback pixels, which a secret fill
+ * (`tainted`, read per capture) withholds; a capture that then times out
+ * before the step clock does is the policy denial it is, not an engine
+ * timeout, since only those pixels could have answered.
  */
 export declare function retryingObserve(options: {
-    readonly observe: (operation: OperationContext) => Promise<Observation>;
+    readonly observe: (operation: OperationContext, pixelFallback: boolean) => Promise<Observation>;
     readonly operation: () => OperationContext;
     readonly guard: (cause?: unknown) => void;
     readonly signal: AbortSignal;
     readonly api: string;
+    readonly fallback: boolean;
+    readonly tainted: () => boolean;
 }): Promise<Observation>;

package/dist/agent/phases.js

@@ -4,7 +4,7 @@
  * these, so event recording, `--debug` buckets, tracing, deadline semantics,
  * and observation race-hardening cannot drift between the two paths.
  */
-import { asEngineError, E2EError } from '../internal/errors.js';
+import { asEngineError, isE2EError } from '../internal/errors.js';
 import { timestamp } from '../internal/ids.js';
 import { POLL_INTERVAL_MS, sleep } from '../internal/time.js';
 import { AgentError, toAgentError } from './error.js';
@@ -112,14 +112,23 @@ function timedOutAtDeadline(cause, deadline) {
  * re-read rather than surfaced as a failed call. `guard` is the caller's
  * clock check, so a capture that outlives the deadline reports the step's own
  * timeout rather than whichever transport error the truncated budget produced.
+ * `fallback` asks the engine for fallback pixels, which a secret fill
+ * (`tainted`, read per capture) withholds; a capture that then times out
+ * before the step clock does is the policy denial it is, not an engine
+ * timeout, since only those pixels could have answered.
  */
 export async function retryingObserve(options) {
     for (;;) {
+        const withheld = options.fallback && options.tainted();
         try {
-            return await options.observe(options.operation());
+            return await options.observe(options.operation(), options.fallback && !withheld);
         }
         catch (cause) {
             options.guard(cause);
+            if (withheld && asEngineError(cause)?.code === 'OPERATION_TIMEOUT') {
+                throw new AgentError('POLICY_DENIED', `${options.api} could not read the semantic tree, and its screenshot fallback is denied: ` +
+                    'a secret was filled in this attempt, so no pixels leave the runner until it ends (PIXEL_TAINTED)', { cause });
+            }
             // Structural, not instanceof: an engine a config file imported lives in
             // another module registry, and its retryable race would otherwise fail
             // the observation the moment a page navigates under it.
@@ -133,7 +142,7 @@ export async function retryingObserve(options) {
 }
 /** Event code for a failed phase: the runner or engine code, or the error's name. */
 function phaseErrorCode(cause) {
-    if (cause instanceof E2EError)
+    if (isE2EError(cause))
         return cause.code;
     const engineError = asEngineError(cause);
     if (engineError !== undefined)

package/dist/agent/prompts.js

@@ -95,6 +95,9 @@ export const JUDGMENT_REQUEST = [
     'Decide whether the instruction is true for the observation right now.',
     'Answer "holds" only when the observation shows it is true, and "fails" only when the observation shows it is false.',
     'Answer "inconclusive" when the observation does not contain enough evidence to decide either way: the relevant part is not on screen, is still loading, or cannot be read. Never guess.',
+    'When the same value or state is shown in more than one place, such as an order total in a summary and again as the amount on a pay button, the instruction holds only when every place agrees with it; one place that contradicts it is a "fails", even if another agrees.',
+    'This applies only when the instruction does not say where to look: an instruction that names the place, such as "the order summary total", is judged on that place alone.',
+    'It is about one value shown twice, not about different items: a claim about some item, such as "a todo is marked done", holds when one item matches.',
     'Quotation marks in the instruction delimit the words to look for; the marks themselves, their style (straight or curly), and the punctuation around them are not part of those words, so text that reads the same holds.',
     'Write the explanation first and let the verdict follow from it: the two must agree.',
     'Respond with { "protocolVersion": "agent-judgment-2", "explanation": <short reason grounded in the observation>, "verdict": "holds" | "fails" | "inconclusive" }.',

package/dist/agent/replay.js

@@ -150,22 +150,25 @@ export async function replayTrace(host, trace, options = {}) {
                     await planned.invoke();
                     break;
                 case 'scroll': {
-                    if (planned.list === undefined) {
-                        // A viewport scroll relocates nothing, so each later repeat takes
-                        // a settled look of its own, as the live loop did between them.
-                        for (let index = 0; index < planned.times; index += 1) {
+                    // A scroll on a list is paced by the relocation before each repeat.
+                    // A viewport scroll relocates nothing, so each later repeat takes a
+                    // settled look of its own, as the live loop did between them. A
+                    // list judged lost scrolls as the viewport from then on, instead of
+                    // waiting out the relocation backoff again on every repeat.
+                    let list = planned.list;
+                    for (let index = 0; index < planned.times; index += 1) {
+                        if (list === undefined) {
                             if (index > 0)
                                 await host.observe('held-still');
                             await host.actions.scroll(planned.direction);
-                            repeated += 1;
                         }
-                        break;
-                    }
-                    // A scroll on a list is paced by the relocation before each repeat.
-                    for (let index = 0; index < planned.times; index += 1) {
-                        const lost = await scrollOnce(host, planned.direction, planned.list, index === 0 ? look : HELD_STILL);
-                        if (lost !== undefined)
-                            return stop(lost, partial());
+                        else {
+                            const scrolled = await scrollOnce(host, planned.direction, list, index === 0 ? look : HELD_STILL);
+                            if (scrolled.kind === 'failed')
+                                return stop(scrolled.failure, partial());
+                            if (scrolled.kind === 'viewport')
+                                list = undefined;
+                        }
                         repeated += 1;
                     }
                     break;
@@ -377,12 +380,12 @@ async function scrollOnce(host, direction, list, look) {
     const relocated = await relocate(host, list.descriptor, look);
     if (relocated.kind === 'found') {
         await host.actions.scroll(direction, { id: relocated.id });
-        return undefined;
+        return { kind: 'list' };
     }
     if ((list.spans ?? 0) < MAIN_LIST_SHARE)
-        return relocated.failure;
+        return { kind: 'failed', failure: relocated.failure };
     await host.actions.scroll(direction);
-    return undefined;
+    return { kind: 'viewport' };
 }
 /** A fresh look that proves the screen holds still: the first look of a replay without a start capture, and the look after an action that moved the screen. */
 const HELD_STILL = { kind: 'capture', settle: 'held-still' };

package/dist/agent/step-cache.d.ts

@@ -117,7 +117,8 @@ export declare class StepTraceSession {
      * self-finalized verdict on a full replay whose postcondition holds;
      * undefined dispatches the executor — after a miss from the top, after a
      * divergence mid-step with `replayedPrefix` set. Every failure to replay is
-     * a miss, never an error; only runtime hard stops propagate.
+     * a miss, never an error; only runtime hard stops and a policy denial on
+     * the opening look propagate.
      */
     begin(): Promise<StepVerdict | undefined>;
     /**

package/dist/agent/step-cache.js

@@ -136,7 +136,8 @@ export class StepTraceSession {
      * self-finalized verdict on a full replay whose postcondition holds;
      * undefined dispatches the executor — after a miss from the top, after a
      * divergence mid-step with `replayedPrefix` set. Every failure to replay is
-     * a miss, never an error; only runtime hard stops propagate.
+     * a miss, never an error; only runtime hard stops and a policy denial on
+     * the opening look propagate.
      */
     async begin() {
         this.startedMs = Date.now();
@@ -297,7 +298,7 @@ export class StepTraceSession {
      * when this step may write. Settled as far as the capture's purpose asks.
      */
     async captureStart(purpose) {
-        const observation = await probeScreen(this.host, purpose === 'path-only' ? 'raw' : 'held-still');
+        const observation = await probeScreen(this.host, purpose === 'path-only' ? 'raw' : 'held-still', true);
         this.startPath = observation?.path;
         if (this.recorder !== undefined && observation?.kind === 'semantic')
             this.startNodes = observation.nodes;
@@ -565,14 +566,17 @@ function baselineScreen(screens, endPath) {
  * One cache capture, settled as far as `mode` asks, or undefined when the
  * surface cannot be observed right now, which is the executor's business,
  * not the cache's. Runtime hard stops (timeout, cancellation) are the step's
- * truth even when they land during cache bookkeeping, and propagate.
+ * truth even when they land during cache bookkeeping, and propagate. So does
+ * a policy denial on the step's opening look (`opening`): the executor's
+ * first look reads the same screen under the same policy, and would spend
+ * another operation budget to be denied again.
  */
-async function probeScreen(host, mode) {
+async function probeScreen(host, mode, opening = false) {
     try {
         return await host.observe(mode);
     }
     catch (cause) {
-        if (isRuntimeHardStop(cause))
+        if (isRuntimeHardStop(cause) || (opening && isAgentError(cause) && cause.code === 'POLICY_DENIED'))
             throw cause;
         return undefined;
     }

package/dist/agent/tool-loop.js

@@ -15,7 +15,7 @@ import { MODEL_REQUEST_HEADERS } from '../internal/client-identity.js';
 import { ConfigurationError, withHint } from '../internal/errors.js';
 import { failureHint, isAbort, TRANSPORT_RETRIES } from './model/sdk.js';
 import { isContextOverflow } from './model/overflow.js';
-import { isForcedToolCallSkipped, isForcedToolChoiceDowngraded, isForcedToolChoiceRejected } from './model/tool-choice.js';
+import { isForcedToolCallMismatched, isForcedToolCallSkipped, isForcedToolChoiceDowngraded, isForcedToolChoiceRejected, } from './model/tool-choice.js';
 import { withStallGuard } from './model/stall.js';
 import { providerHints } from './model/provider-hints.js';
 import { isScreenOutput, toolResultTexts } from './screen-update.js';
@@ -193,6 +193,13 @@ class LoopRun {
                     prompt = shrunk;
                     continue;
                 }
+                const corrected = this.correctForcedTurn(cause, tracker);
+                if (corrected === 'out-of-turns')
+                    break;
+                if (corrected !== undefined) {
+                    prompt = corrected;
+                    continue;
+                }
                 const freed = this.freeToolChoiceRetry(cause, tracker);
                 if (freed !== undefined) {
                     prompt = freed;
@@ -275,6 +282,49 @@ class LoopRun {
             { role: 'user', content: TEXT_REPLY_NOTICE },
         ];
     }
+    /**
+     * A turn forced to call `complete_step` that called other tools instead:
+     * the SDK throws `ToolChoiceViolationError` before running any of them. It
+     * is handled like a call to a tool the turn does not offer: the turn counts,
+     * each call goes back to the model as an error result, and the model is
+     * asked again on the same turn budget. Out of turns, the step ends as
+     * `STEP_NO_CONCLUSION`, like any step that never concluded.
+     */
+    correctForcedTurn(cause, tracker) {
+        if (this.lastRequest === undefined || this.context.signal.aborted || this.hardStop !== undefined)
+            return undefined;
+        if (!isForcedToolCallMismatched(cause))
+            return undefined;
+        const reply = thrownReply(cause.content);
+        const results = reply.calls.map((call) => ({
+            type: 'tool-result',
+            toolCallId: call.toolCallId,
+            toolName: call.toolName,
+            output: {
+                type: 'error-text',
+                value: `${call.toolName} did not run: only complete_step is available now. Call complete_step with your verdict.`,
+            },
+        }));
+        this.recordThrownTurn(tracker, reply.calls.map((call) => `${call.toolName}(${truncate(safeJson(call.input), MAX_TURN_CALL_CHARS)})`), [
+            skippedReplyText(cause.content),
+            ...results.map((result) => `[${result.toolName}] error: ${result.output.value}`),
+        ].filter((line) => line !== '').join('\n'));
+        if (this.turnsUsed >= this.maxTurns)
+            return 'out-of-turns';
+        this.note(`turn ${String(this.turnsUsed)} called other tools in place of complete_step: asking again`);
+        this.turnOffset = this.turnsUsed;
+        return [...this.lastRequest, reply.message, { role: 'tool', content: results }];
+    }
+    /**
+     * Counts a turn the provider answered, and billed, before the SDK threw on
+     * it. The SDK reports no usage for such a turn.
+     */
+    recordThrownTurn(tracker, calls, outcome) {
+        tracker.onStepEnd({ usage: UNREPORTED_USAGE, providerMetadata: undefined, reasoningText: undefined });
+        this.turnsUsed += 1;
+        this.turns.push({ index: this.turnsUsed, calls, outcome, notes: [] });
+        this.attachTranscript();
+    }
     /**
      * A model that refuses a forced tool choice (HTTP 400 naming
      * `tool_choice`) is asked again with `auto` and a tool-calls-only rule in
@@ -290,10 +340,7 @@ class LoopRun {
         if (this.context.signal.aborted || this.hardStop !== undefined)
             return undefined;
         if (isForcedToolCallSkipped(cause)) {
-            // The provider answered, and billed, before the SDK threw: the turn counts.
-            tracker.onStepEnd({ usage: UNREPORTED_USAGE, providerMetadata: undefined, reasoningText: undefined });
-            this.turnsUsed += 1;
-            this.turns.push({ index: this.turnsUsed, calls: [], outcome: skippedReplyText(cause.content), notes: [] });
+            this.recordThrownTurn(tracker, [], skippedReplyText(cause.content));
             this.note(`turn ${String(this.turnsUsed)} answered without the forced tool call: retrying with auto`);
         }
         else if (isForcedToolChoiceRejected(cause)) {
@@ -619,6 +666,46 @@ function skippedReplyText(content) {
         .trim();
     return text === '' ? '' : `assistant: ${truncate(text, MAX_TURN_TEXT_CHARS)}`;
 }
+/**
+ * A reply the SDK threw on, as the assistant message the SDK's own history
+ * would carry: its text, reasoning, and tool calls, each with the provider's
+ * metadata (reasoning signatures and Gemini's thought signatures ride there),
+ * and the tool calls apart, to answer each with a result.
+ */
+function thrownReply(content) {
+    const parts = [];
+    const calls = [];
+    for (const part of content) {
+        const metadata = part.providerMetadata === undefined ? {} : { providerOptions: part.providerMetadata };
+        if (part.type === 'text' && typeof part.text === 'string' && part.text !== '') {
+            parts.push({ type: 'text', text: part.text, ...metadata });
+        }
+        else if (part.type === 'reasoning' && typeof part.text === 'string') {
+            parts.push({ type: 'reasoning', text: part.text, ...metadata });
+        }
+        else if (part.type === 'tool-call' && typeof part.toolCallId === 'string' && typeof part.toolName === 'string') {
+            const call = {
+                type: 'tool-call',
+                toolCallId: part.toolCallId,
+                toolName: part.toolName,
+                input: typeof part.input === 'string' ? parseToolInput(part.input) : part.input,
+                ...metadata,
+            };
+            parts.push(call);
+            calls.push(call);
+        }
+    }
+    return { message: { role: 'assistant', content: parts }, calls };
+}
+/** A raw tool call's input for the history: the parsed JSON, or the text itself when it does not parse. */
+function parseToolInput(input) {
+    try {
+        return JSON.parse(input);
+    }
+    catch {
+        return input;
+    }
+}
 function describeOutput(output) {
     if (isScreenOutput(output))
         return `${output.text}\n[screenshot, ${String(output.pixels.data.byteLength)} bytes]`;

package/dist/cache/trace.js

@@ -203,7 +203,7 @@ function readRecordedAction(document) {
     switch (name) {
         case 'type': {
             const target = readDescriptor(raw['target']);
-            const value = readInputText(raw['value']);
+            const value = readTypedValue(raw['value']);
             if (target === undefined || value === undefined)
                 return undefined;
             return { name: 'type', summary, target, value };
@@ -310,7 +310,7 @@ function readRecordedAction(document) {
         case 'back':
             return { name: 'back', summary };
         case 'typeText': {
-            const value = readInputText(raw['value']);
+            const value = readTypedValue(raw['value']);
             if (value === undefined || typeof raw['replace'] !== 'boolean')
                 return undefined;
             return { name: 'typeText', summary, value, replace: raw['replace'] };
@@ -612,3 +612,7 @@ function readInputText(value) {
     }
     return value;
 }
+/** A typed value: `readInputText`, except that `''` is valid, since typing it clears a field. */
+function readTypedValue(value) {
+    return value === '' ? value : readInputText(value);
+}

package/dist/cli/bin.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { unsupportedNodeMessage } from '../internal/node-version.js';
+import { unsupportedRuntimeMessage } from '../internal/node-version.js';
 // Checked before the CLI module loads: that module and its dependencies are
 // what an old runtime would fail on, with a stack trace instead of a sentence.
-const unsupported = unsupportedNodeMessage(process.versions.node);
+const unsupported = unsupportedRuntimeMessage();
 if (unsupported !== undefined) {
     process.stderr.write(`${unsupported}\n`);
     process.exit(2);

package/dist/cli/index.js

@@ -7,6 +7,7 @@ import { detectPackageManager, execCommand, runScriptCommand } from '../internal
 import { packageVersion } from '../internal/package-version.js';
 import { classifyError, exitCodeForCategory } from '../internal/errors.js';
 import { list, run } from '../run/runner.js';
+import { claimRunnerOutput } from './run-output.js';
 import { explore, STEP_BOUNDS, TIMEOUT_BOUNDS } from '../explore/index.js';
 import { BUILTIN_REPORTERS, isBuiltinReporter } from '../report/builtin.js';
 import { bounded } from '../report/format.js';
@@ -401,11 +402,14 @@ function createProgram(version, telemetry) {
         .description('Serve an MCP server over stdio for a coding agent such as Claude Code or Cursor: open_session opens a live session on one target of any config the agent names, call runs the session\'s tools (observe, tap, type, press, select, scroll, navigate, type_secret, locate, screenshot, and the project\'s own), tools describes them, close_session ends it. The agent explores the real app before writing a test. Register it with the client, e.g. claude mcp add e2e -- npx e2e mcp.')
         .option('--config <path>', 'config file (default: the nearest e2e.config.ts)')
         .option('--target <name>', 'target every session opens on (default: the only target, or the one open_session names)')
-        .option('--headless', 'hide the UI during live sessions (default: headed outside CI)')
+        .option('--headed', 'show the UI in sessions whose open_session does not set headed, when the engine supports it')
+        // Sessions were headed by default before 0.18 and took --headless; a client config that still passes it
+        // asks for the default now, and a refused flag would surface as nothing but a failed connection.
+        .addOption(new Option('--headless').hideHelp())
         .option('--max-sessions <n>', `sessions open at once, each with its own browser or device, ${SESSION_BOUNDS.min} through ${SESSION_BOUNDS.max} (default: ${SESSION_BOUNDS.default})`, parseBoundedInt(SESSION_BOUNDS))
         .addHelpText('after', [
         '',
-        examples(['e2e mcp', 'e2e mcp --target web --headless', 'e2e mcp --max-sessions 8', 'claude mcp add e2e -- npx e2e mcp']),
+        examples(['e2e mcp', 'e2e mcp --target web --headed', 'e2e mcp --max-sessions 8', 'claude mcp add e2e -- npx e2e mcp']),
         '',
         docsLine('/reference/mcp'),
     ].join('\n'))
@@ -466,28 +470,35 @@ function createProgram(version, telemetry) {
     // Each value is what its parser returned, so a bad one never reaches here.
     options, command) => {
         rejectForwardedFlags(command, files);
-        return runToOutcome(telemetry, command, (signals) => run({
-            files,
-            configPath: options.config,
-            targetIds: options.target,
-            ...selectionRunOptions(options),
-            headed: options.headed,
-            agent: options.agent,
-            retries: options.retries,
-            workers: options.workers,
-            maxFailures: options.maxFailures,
-            repeatEach: options.repeatEach,
-            reporters: options.reporter,
-            output: options.output,
-            noCache: options.cache === false,
-            strictCache: options.strictCache,
-            debug: options.debug,
-            aiTrace: options.aiTrace,
-            trace: recordingOption(options.trace),
-            video: recordingOption(options.video),
-            interruptSignal: signals.interruptSignal,
-            forceSignal: signals.forceSignal,
-        }));
+        const output = claimRunnerOutput();
+        try {
+            await runToOutcome(telemetry, command, (signals) => run({
+                files,
+                configPath: options.config,
+                targetIds: options.target,
+                ...selectionRunOptions(options),
+                headed: options.headed,
+                agent: options.agent,
+                retries: options.retries,
+                workers: options.workers,
+                maxFailures: options.maxFailures,
+                repeatEach: options.repeatEach,
+                reporters: options.reporter,
+                output: options.output,
+                noCache: options.cache === false,
+                strictCache: options.strictCache,
+                debug: options.debug,
+                aiTrace: options.aiTrace,
+                trace: recordingOption(options.trace),
+                video: recordingOption(options.video),
+                interruptSignal: signals.interruptSignal,
+                forceSignal: signals.forceSignal,
+                processOutput: output,
+            }));
+        }
+        finally {
+            output.end();
+        }
     });
     program
         .command('explore')

package/dist/cli/init/mcp-config.d.ts

@@ -25,6 +25,7 @@ export declare function findRegisteredMcpFiles(cwd: string): string[];
 /**
  * Plans the writes for the given files. A file without the entry gets it
  * merged in; one whose entry already matches needs nothing and is left out.
- * Other servers, other keys, and the file's indentation are preserved.
+ * Extra settings on the e2e entry, other servers, other keys, and the file's
+ * indentation are preserved.
  */
 export declare function planMcpRegistration(cwd: string, files: readonly string[]): McpRegistration[];

package/dist/cli/init/mcp-config.js

@@ -45,7 +45,8 @@ export function findRegisteredMcpFiles(cwd) {
 /**
  * Plans the writes for the given files. A file without the entry gets it
  * merged in; one whose entry already matches needs nothing and is left out.
- * Other servers, other keys, and the file's indentation are preserved.
+ * Extra settings on the e2e entry, other servers, other keys, and the file's
+ * indentation are preserved.
  */
 export function planMcpRegistration(cwd, files) {
     const registrations = [];
@@ -55,9 +56,13 @@ export function planMcpRegistration(cwd, files) {
         const servers = typeof document.mcpServers === 'object' && document.mcpServers !== null && !Array.isArray(document.mcpServers)
             ? document.mcpServers
             : {};
-        if (JSON.stringify(servers[MCP_SERVER_NAME]) === JSON.stringify(SERVER_ENTRY))
+        const existing = servers[MCP_SERVER_NAME];
+        const entry = typeof existing === 'object' && existing !== null && !Array.isArray(existing)
+            ? { ...existing, ...SERVER_ENTRY }
+            : SERVER_ENTRY;
+        if (JSON.stringify(existing) === JSON.stringify(entry))
             continue;
-        const merged = { ...document, mcpServers: { ...servers, [MCP_SERVER_NAME]: SERVER_ENTRY } };
+        const merged = { ...document, mcpServers: { ...servers, [MCP_SERVER_NAME]: entry } };
         const original = existsSync(absolute) ? readFileSync(absolute, 'utf8') : undefined;
         const indent = original?.match(/\n([\t ]+)"/)?.[1] ?? '  ';
         registrations.push({

package/dist/cli/init/sibling-versions.json

@@ -1 +1 @@
-{"@e2e-dev/web":"0.12.0","@e2e-dev/mobile":"0.9.2"}
+{"@e2e-dev/web":"0.13.0","@e2e-dev/mobile":"0.10.0"}