e2e 0.17.0 → 0.18.0

package/dist/internal/node-version.js

@@ -1,10 +1,10 @@
 /**
- * The Node.js floor, checked before the CLI loads anything else. Package
- * managers only warn about `engines`, so an unsupported runtime would
- * otherwise surface as an unrelated TypeError deep inside a run.
+ * The Node.js releases e2e runs on, as a set of release ranges. The CLI checks the floor before it loads
+ * anything else: package managers only warn about `engines`, so an
+ * unsupported runtime would otherwise surface as an unrelated TypeError deep
+ * inside a run.
  */
-/** Mirrors `engines.node` in package.json; a unit test keeps the two in step. */
-export const MINIMUM_NODE_VERSION = '22.12.0';
+import nodeModule from 'node:module';
 function parse(version) {
     const [major = 0, minor = 0, patch = 0] = version
         .replace(/^v/, '')
@@ -12,16 +12,51 @@ function parse(version) {
         .map((part) => Number.parseInt(part, 10) || 0);
     return [major, minor, patch];
 }
-/** Explains an unsupported runtime, or undefined when `current` meets the floor. */
-export function unsupportedNodeMessage(current, minimum = MINIMUM_NODE_VERSION) {
-    const have = parse(current);
-    const need = parse(minimum);
+function atLeast(have, need) {
     for (let i = 0; i < 3; i += 1) {
-        if (have[i] > need[i])
-            return undefined;
-        if (have[i] < need[i]) {
-            return `e2e requires Node.js ${minimum} or newer; this is Node.js ${current.replace(/^v/, '')}. Upgrade Node.js, or switch versions with your version manager (nvm use 22, fnm use 22, volta pin node@22).`;
-        }
+        if (have[i] !== need[i])
+            return have[i] > need[i];
     }
-    return undefined;
+    return true;
+}
+function within(version, ranges) {
+    const have = parse(version);
+    return ranges.some((range) => ('line' in range ? have[0] === range.line : true) && atLeast(have, range.since));
+}
+/**
+ * Where e2e's TypeScript loader works. It runs on `module.registerHooks`, and
+ * before these releases a CommonJS file an ES module imported cannot
+ * `require()` an ES module the hooks load, such as a project's TypeScript:
+ * Node.js throws reading its own cache (nodejs/node#59679, in 22.22.3 and
+ * 24.8.0). Node.js 23 has no such release.
+ */
+const SUPPORTED = [
+    { line: 22, since: [22, 22, 3] },
+    { since: [24, 8, 0] },
+];
+/** `engines.node` in package.json; a unit test keeps the two in step. */
+export const SUPPORTED_NODE_RANGE = SUPPORTED.map((range) => `${'line' in range ? '^' : '>='}${range.since.join('.')}`).join(' || ');
+/** Explains a Node.js outside `SUPPORTED_NODE_RANGE`, or undefined for one inside it. */
+function unsupportedNodeMessage(current) {
+    if (within(current, SUPPORTED))
+        return undefined;
+    const required = SUPPORTED.map((range) => ('line' in range ? `${range.since.join('.')} or newer on Node.js ${range.line}` : `${range.since.join('.')} or newer`)).join(', or ');
+    return `e2e requires Node.js ${required}; this is Node.js ${current.replace(/^v/, '')}. Upgrade Node.js, or switch versions with your version manager (nvm install 24, fnm install 24, volta install node@24).`;
+}
+/**
+ * Explains a runtime e2e cannot run on, or undefined for one it can: a
+ * Node.js outside `SUPPORTED_NODE_RANGE`, or a runtime that reports a
+ * supported Node.js version without Node.js's `module.registerHooks` (Bun),
+ * which e2e's TypeScript loader runs on, or Deno.
+ */
+export function unsupportedRuntimeMessage(versions = process.versions, hasRegisterHooks = typeof nodeModule.registerHooks === 'function') {
+    // Deno implements module.registerHooks, but not the require() of a native addon from inside a hook that oxc needs.
+    if (versions.deno !== undefined)
+        return `e2e runs on Node.js, not Deno ${versions.deno}: run the CLI with Node.js (npx e2e).`;
+    // Checked before the Node.js version a runtime reports, which upgrading Node.js does not change.
+    if (!hasRegisterHooks) {
+        const runtime = versions.bun !== undefined ? `Bun ${versions.bun}` : 'This runtime';
+        return `e2e runs on Node.js: ${runtime} reports Node.js ${versions.node} but has no module.registerHooks, which e2e's TypeScript loader needs. Run the CLI with Node.js: npx e2e, or bunx e2e (without --bun).`;
+    }
+    return unsupportedNodeMessage(versions.node);
 }

package/dist/internal/package-manager.js

@@ -44,7 +44,7 @@ export function runScriptCommand(manager, name) {
 export function execCommand(manager, command) {
     switch (manager) {
         case 'npm':
-            return `npm exec ${command}`;
+            return `npm exec -- ${command}`;
         case 'pnpm':
             return `pnpm exec ${command}`;
         case 'yarn':

package/dist/internal/realm-slot.d.ts

@@ -1,8 +1,9 @@
 /**
- * Typed accessor for a `Symbol.for` slot on a host object. Test modules load
- * in isolated module realms (tsx), so runner-owned instances are shared
- * through registry symbols instead of module state. All unsafe reads live
- * here; call sites stay fully typed.
+ * Typed accessor for a `Symbol.for` slot on a host object. A project can load
+ * a copy of e2e other than the runner's (a second install, a linked checkout,
+ * a fresh module registry under a test runner), so runner-owned instances are
+ * shared through registry symbols instead of module state. All unsafe reads
+ * live here; call sites stay fully typed.
  */
 export interface RealmSlot<T> {
     set(host: object, value: T): void;

package/dist/internal/redact.d.ts

@@ -37,6 +37,8 @@ export declare class SecretLedger {
     register(name: string, value: string): void;
     /** Bound so it can be handed out as a plain function. */
     readonly redact: (text: string) => string;
+    /** Whether no value is registered, so there is nothing to redact. */
+    get isEmpty(): boolean;
     /** Every registered name and value, in registration order. */
     entries(): readonly (readonly [string, string])[];
     /**

package/dist/internal/redact.js

@@ -527,6 +527,10 @@ export class SecretLedger {
     }
     /** Bound so it can be handed out as a plain function. */
     redact = (text) => this.compile().redact(text);
+    /** Whether no value is registered, so there is nothing to redact. */
+    get isEmpty() {
+        return this.values.length === 0;
+    }
     /** Every registered name and value, in registration order. */
     entries() {
         return this.values.map(([name, value]) => [name, value]);

package/dist/internal/time.d.ts

@@ -12,6 +12,15 @@ export declare class Deadline {
 export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
 /** Canonical polling cadence for locator and assertion loops. */
 export declare const POLL_INTERVAL_MS = 100;
+/**
+ * Whether `cause` is a read a wait's deadline cut off: an operation timeout
+ * of a read that started with less than one poll tick of the wait left, so
+ * it timed out because the wait did, not because the app stopped answering.
+ * A read that started with more and still timed out hung, and its timeout is
+ * the failure. Reads the engine error a locator failure wraps as well as a
+ * bare one.
+ */
+export declare function cutOffAtDeadline(cause: unknown, startedWithMs: number): boolean;
 /** How long a negated assertion must hold before it passes. */
 export declare const NEGATION_GRACE_MS = 1000;
 export interface PollConditionOptions {
@@ -19,12 +28,14 @@ export interface PollConditionOptions {
     readonly signal: AbortSignal;
     readonly negated: boolean;
     /**
-     * Evaluates the positive condition once. Returns undefined when the
-     * condition cannot be evaluated yet: the positive poll keeps waiting and
-     * the negation grace window resets.
+     * Evaluates the positive condition once, every read bounded by
+     * `deadline`: a read on a longer budget outlasts the poll. Returns
+     * undefined when the condition cannot be evaluated yet: the positive poll
+     * keeps waiting and the negation grace window resets.
      */
     evaluate(): Promise<boolean | undefined>;
-    onTimeout(): Error | Promise<Error>;
+    /** Builds the poll's failure; `cause` is the read the deadline cut off, when one did. */
+    onTimeout(cause?: unknown): Error | Promise<Error>;
 }
 /**
  * Polls a condition until it holds (or, when negated, until its negation has
@@ -35,7 +46,12 @@ export interface PollConditionOptions {
  * a slow read counts toward the window. A budget shorter than the window
  * still has to be satisfiable: the negation then only needs to hold for the
  * whole budget, and passes at the deadline on what it has seen, since a read
- * past the deadline has no budget left.
+ * past the deadline has no budget left. A read the deadline cut off (see
+ * `cutOffAtDeadline`) after an earlier one completed saw nothing: the poll
+ * ends there. A negation then passes if it has held long enough by the
+ * time the read is cut off: the read left less than one poll tick unseen, no
+ * more than the gap between any two reads, so a short budget still passes at
+ * its deadline on what it saw.
  */
 export declare function pollCondition(options: PollConditionOptions): Promise<void>;
 /** Races a promise against a timeout; on timeout invokes onTimeout to build the error. */

package/dist/internal/time.js

@@ -1,5 +1,5 @@
 /** Deadline and cancellation helpers. */
-import { E2EError } from './errors.js';
+import { asEngineError, E2EError } from './errors.js';
 export class Deadline {
     endsAt;
     constructor(timeoutMs, now = Date.now()) {
@@ -41,6 +41,20 @@ export function sleep(ms, signal) {
 }
 /** Canonical polling cadence for locator and assertion loops. */
 export const POLL_INTERVAL_MS = 100;
+/**
+ * Whether `cause` is a read a wait's deadline cut off: an operation timeout
+ * of a read that started with less than one poll tick of the wait left, so
+ * it timed out because the wait did, not because the app stopped answering.
+ * A read that started with more and still timed out hung, and its timeout is
+ * the failure. Reads the engine error a locator failure wraps as well as a
+ * bare one.
+ */
+export function cutOffAtDeadline(cause, startedWithMs) {
+    if (startedWithMs >= POLL_INTERVAL_MS)
+        return false;
+    const engineError = asEngineError(cause) ?? asEngineError(cause instanceof Error ? cause.cause : undefined);
+    return engineError?.code === 'OPERATION_TIMEOUT';
+}
 /** How long a negated assertion must hold before it passes. */
 export const NEGATION_GRACE_MS = 1000;
 /**
@@ -52,7 +66,12 @@ export const NEGATION_GRACE_MS = 1000;
  * a slow read counts toward the window. A budget shorter than the window
  * still has to be satisfiable: the negation then only needs to hold for the
  * whole budget, and passes at the deadline on what it has seen, since a read
- * past the deadline has no budget left.
+ * past the deadline has no budget left. A read the deadline cut off (see
+ * `cutOffAtDeadline`) after an earlier one completed saw nothing: the poll
+ * ends there. A negation then passes if it has held long enough by the
+ * time the read is cut off: the read left less than one poll tick unseen, no
+ * more than the gap between any two reads, so a short budget still passes at
+ * its deadline on what it saw.
  */
 export async function pollCondition(options) {
     const { deadline, negated } = options;
@@ -61,8 +80,21 @@ export async function pollCondition(options) {
     let readAt = startedAt;
     let holdingSince;
     const holds = (now) => holdingSince !== undefined && now - holdingSince >= grace;
+    let sampled = false;
     for (;;) {
-        const value = await options.evaluate();
+        const startedWithMs = deadline.remaining(readAt);
+        let value;
+        try {
+            value = await options.evaluate();
+            sampled = true;
+        }
+        catch (cause) {
+            if (!sampled || !cutOffAtDeadline(cause, startedWithMs))
+                throw cause;
+            if (negated && holds(Math.min(Date.now(), deadline.endsAt)))
+                return;
+            throw await options.onTimeout(cause);
+        }
         if (!negated) {
             if (value === true)
                 return;

package/dist/locator/engine.js

@@ -3,7 +3,7 @@ import {} from '../engine/surface.js';
 import { asEngineError, ConfigurationError, E2EError, TestError, translateEngineError, } from '../internal/errors.js';
 import { requireKey } from '../internal/keys.js';
 import { describeExpression, expressionHints } from './expression.js';
-import { Deadline, POLL_INTERVAL_MS, sleep } from '../internal/time.js';
+import { cutOffAtDeadline, Deadline, POLL_INTERVAL_MS, sleep } from '../internal/time.js';
 /** Canonical visibility predicate over a semantic node snapshot. */
 export function isNodeVisible(node) {
     return node !== null && node.states?.hidden !== true;
@@ -96,16 +96,22 @@ export class LocatorEngine {
      * matches, and a read that promised not to wait must not wait for it.
      */
     async resolveOnce(expression, deadline, missingFrame = 'wait') {
+        let retried;
         for (;;) {
+            const startedWithMs = deadline.remaining();
             try {
                 return await this.session.locate(expression, this.operationWithin(deadline));
             }
             catch (cause) {
+                // A retry the deadline cut off saw nothing new: the wait ends on the failure it was retrying.
+                if (retried !== undefined && cutOffAtDeadline(cause, startedWithMs))
+                    throw translateLocatorError(retried, expression);
                 const engineError = asEngineError(cause);
                 if (engineError?.retryable === true) {
                     if (missingFrame === 'empty' && engineError.code === 'FRAME_NOT_FOUND')
                         return [];
                     if (!deadline.expired()) {
+                        retried = cause;
                         await sleep(POLL_INTERVAL_MS, this.signal);
                         continue;
                     }
@@ -120,15 +126,31 @@ export class LocatorEngine {
      */
     async resolveExactlyOne(expression, deadline) {
         const startedMs = Date.now();
+        // The wait as it happened: a deadline capped by the test's remaining
+        // budget waited less than the action timeout, and the report says so.
+        const notFound = (cause) => new TestError('LOCATOR_NOT_FOUND', `locator matched no nodes within ${describeExpression(expression)}`, {
+            details: locatorDetails(expression, Date.now() - startedMs),
+            ...(cause === undefined ? {} : { cause }),
+        });
+        let sampled = false;
         for (;;) {
-            const ref = assertSingle(await this.resolveOnce(expression, deadline), expression);
+            const startedWithMs = deadline.remaining();
+            let refs;
+            try {
+                refs = await this.resolveOnce(expression, deadline);
+            }
+            catch (cause) {
+                // A resolve the deadline cut off, after one that matched nothing, is the wait running out.
+                if (sampled && cutOffAtDeadline(cause, startedWithMs))
+                    throw notFound(cause);
+                throw cause;
+            }
+            sampled = true;
+            const ref = assertSingle(refs, expression);
             if (ref !== null)
                 return ref;
-            if (deadline.expired()) {
-                // The wait as it happened: a deadline capped by the test's remaining
-                // budget waited less than the action timeout, and the report says so.
-                throw new TestError('LOCATOR_NOT_FOUND', `locator matched no nodes within ${describeExpression(expression)}`, { details: locatorDetails(expression, Date.now() - startedMs) });
-            }
+            if (deadline.expired())
+                throw notFound();
             await sleep(POLL_INTERVAL_MS, this.signal);
         }
     }
@@ -275,16 +297,30 @@ export class LocatorEngine {
         if (this.session.actions.has('scrollIntoView')) {
             await this.performUntil(expression, { kind: 'scrollIntoView' }, deadline);
         }
+        const notVisible = (cause) => new TestError('LOCATOR_NOT_FOUND', `locator did not become visible with a box to act within: ${describeExpression(expression)}`, {
+            details: locatorDetails(expression, Date.now() - startedMs),
+            ...(cause === undefined ? {} : { cause }),
+        });
+        let sampled = false;
         for (;;) {
-            const { node } = await this.tryRead(expression, deadline);
+            const startedWithMs = deadline.remaining();
+            let node;
+            try {
+                ({ node } = await this.tryRead(expression, deadline));
+            }
+            catch (cause) {
+                if (sampled && cutOffAtDeadline(cause, startedWithMs))
+                    throw notVisible(cause);
+                throw cause;
+            }
+            sampled = true;
             const rect = isNodeVisible(node) ? node.rect : undefined;
             if (rect !== undefined) {
                 await this.dispatchAt({ x: rect.x + offset.x, y: rect.y + offset.y }, action, deadline);
                 return;
             }
-            if (deadline.expired()) {
-                throw new TestError('LOCATOR_NOT_FOUND', `locator did not become visible with a box to act within: ${describeExpression(expression)}`, { details: locatorDetails(expression, Date.now() - startedMs) });
-            }
+            if (deadline.expired())
+                throw notVisible();
             await sleep(POLL_INTERVAL_MS, this.signal);
         }
     }

package/dist/locator/screen.js

@@ -12,7 +12,7 @@ import { obj } from '../internal/objects.js';
 import { isTextMatch, normalizeText } from '../internal/text.js';
 import { attributeOf, denySecureRead, isNodeVisible, locatorDetails } from './engine.js';
 import { describeExpression, filterExpression, indexExpression, roleQuery, testIdQuery, textQuery, } from './expression.js';
-import { POLL_INTERVAL_MS, pollCondition, sleep } from '../internal/time.js';
+import { cutOffAtDeadline, POLL_INTERVAL_MS, pollCondition, sleep } from '../internal/time.js';
 /**
  * Internals hang off the locator object itself under a global symbol so that
  * an expect() imported in an isolated test-module realm can still reach them.
@@ -127,10 +127,15 @@ class ScreenImpl {
     }
     async swipe(options) {
         if (isSwipePath(options)) {
-            rejectUnknownOptions('swipe', options, ['from', 'to']);
+            rejectUnknownOptions('swipe', options, ['from', 'to', 'duration']);
             const from = requirePoint(options.from, 'swipe from');
             const to = requirePoint(options.to, 'swipe to');
-            await this.context.steps.run('screen', 'screen.swipe', `${describePoint(from)} → ${describePoint(to)}`, () => this.context.engine.performAt(from, { kind: 'swipeTo', target: to }));
+            const durationMs = validateSwipeDuration(options.duration);
+            await this.context.steps.run('screen', 'screen.swipe', `${describePoint(from)} → ${describePoint(to)}`, () => this.context.engine.performAt(from, obj({
+                kind: 'swipeTo',
+                target: to,
+                durationMs,
+            })));
             return;
         }
         rejectUnknownOptions('swipe', options, ['direction', 'momentum']);
@@ -160,8 +165,19 @@ class ScreenImpl {
                 details: locatorDetails(internals.expression, Date.now() - startedMs),
                 ...(cause === undefined ? {} : { cause }),
             });
+            let sampled = false;
             for (;;) {
-                const { node } = await engine.tryRead(internals.expression, deadline);
+                const startedWithMs = deadline.remaining();
+                let node;
+                try {
+                    ({ node } = await engine.tryRead(internals.expression, deadline));
+                }
+                catch (cause) {
+                    if (sampled && cutOffAtDeadline(cause, startedWithMs))
+                        throw notVisible(cause);
+                    throw cause;
+                }
+                sampled = true;
                 if (isNodeVisible(node))
                     return;
                 if (deadline.expired())
@@ -399,8 +415,9 @@ class LocatorImpl extends ScreenImpl {
                     const { node } = await engine.tryRead(this.expression, deadline, ABSENCE_STATES.has(state) ? 'empty' : 'wait');
                     return inWaitForState(node, state);
                 },
-                onTimeout: () => new TestError('LOCATOR_NOT_FOUND', `locator did not become ${state}: ${this.label}`, {
+                onTimeout: (cause) => new TestError('LOCATOR_NOT_FOUND', `locator did not become ${state}: ${this.label}`, {
                     details: locatorDetails(this.expression, Date.now() - startedMs),
+                    ...(cause === undefined ? {} : { cause }),
                 }),
             });
         }, { verifies: true });
@@ -485,6 +502,15 @@ function validateLongPress(durationMs) {
     }
     return durationMs;
 }
+/** Validates the shared swipe duration bound; none named leaves the gesture to the engine's default. */
+function validateSwipeDuration(duration) {
+    if (duration === undefined)
+        return undefined;
+    if (!Number.isInteger(duration) || duration < 16 || duration > 10_000) {
+        throw new TestError('INVALID_ARGUMENT', `swipe duration must be an integer from 16 through 10000, got ${String(duration)}`);
+    }
+    return duration;
+}
 /**
  * The `modifiers` of a click, validated: a list of distinct key modifiers,
  * spread into the action only when it names one.

package/dist/mcp/output.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What the `e2e mcp` process prints besides the protocol. User code runs in
+ * this process (the config's top-level code, project tools, engines), and
+ * what it writes to stdout or stderr reaches the operator's stderr redacted
+ * with every secret value the process knows, as a test's output leaves an
+ * `e2e run` worker. The server's own diagnostics are redacted where they are
+ * written and pass as they are.
+ */
+import { type SecretLedger } from '../internal/redact.ts';
+export type OutputStream = 'stdout' | 'stderr';
+/** Writes text to the operator's stderr; the callback fires once the stream took it. Answers false while the stream is backed up, like `Writable.write`. */
+export type OutputSink = (text: string, callback?: () => void) => boolean;
+export declare class McpOutput {
+    private readonly sink;
+    /** Each stream's bytes decoded on their own, so a character split across writes stays whole. */
+    private readonly decoders;
+    /** One redactor for both streams: they land on one stderr, where a value split across them reads whole. */
+    private readonly redactor;
+    /** Config loads in flight: until each ends, what anyone prints is held. */
+    private loading;
+    /** Whether a load in flight failed, so its secrets are unknown and what is held cannot be redacted. */
+    private loadFailed;
+    /** Tool calls in flight: a held tail is released only once none is, since any of them may be partway through a value. */
+    private calls;
+    private held;
+    /** Whether the last text passed on ended its line. */
+    private atLineStart;
+    constructor(sink: OutputSink, ledger: SecretLedger);
+    /**
+     * One write of user code to `stream`, redacted across writes: the tail a
+     * later write could complete into a value waits for it, or for the end of
+     * the tool calls in flight. Held while a config loads. Answers what the
+     * sink did.
+     */
+    write(stream: OutputStream, chunk: string | Uint8Array, callback?: () => void): boolean;
+    /** One line of the server's own, already redacted where it was written; on a line of its own even when user code left one unfinished. */
+    log(line: string): void;
+    /** A line of the server's that carries user text (an error nobody caught): redacted and held like what user code writes. */
+    report(line: string): void;
+    /**
+     * Runs `load`, a config load that registers the config's secrets, holding
+     * what anyone prints until it ends: the config's top-level code may print
+     * a value before the process knows it is one. Released redacted once every
+     * load in flight succeeded; withheld when one failed, since the secrets of
+     * a config that did not load are unknown.
+     */
+    withholdDuring<T>(load: () => Promise<T>): Promise<T>;
+    /**
+     * Runs one tool call. Once no call is in flight, the tail held for a later
+     * write is released, redacted: user code that printed without a newline is
+     * seen when its call ends, not when the server exits.
+     */
+    duringCall<T>(call: () => Promise<T>): Promise<T>;
+    /** Releases what is still held, redacted; nothing more will follow. Output held for a load still in flight is withheld. */
+    end(): void;
+    private releaseHeld;
+    private withhold;
+    private emit;
+}

package/dist/mcp/output.js

@@ -0,0 +1,129 @@
+/**
+ * What the `e2e mcp` process prints besides the protocol. User code runs in
+ * this process (the config's top-level code, project tools, engines), and
+ * what it writes to stdout or stderr reaches the operator's stderr redacted
+ * with every secret value the process knows, as a test's output leaves an
+ * `e2e run` worker. The server's own diagnostics are redacted where they are
+ * written and pass as they are.
+ */
+import { StringDecoder } from 'node:string_decoder';
+import { StreamRedactor } from '../internal/redact.js';
+export class McpOutput {
+    sink;
+    /** Each stream's bytes decoded on their own, so a character split across writes stays whole. */
+    decoders = {
+        stdout: new StringDecoder('utf8'),
+        stderr: new StringDecoder('utf8'),
+    };
+    /** One redactor for both streams: they land on one stderr, where a value split across them reads whole. */
+    redactor;
+    /** Config loads in flight: until each ends, what anyone prints is held. */
+    loading = 0;
+    /** Whether a load in flight failed, so its secrets are unknown and what is held cannot be redacted. */
+    loadFailed = false;
+    /** Tool calls in flight: a held tail is released only once none is, since any of them may be partway through a value. */
+    calls = 0;
+    held = [];
+    /** Whether the last text passed on ended its line. */
+    atLineStart = true;
+    constructor(sink, ledger) {
+        this.sink = sink;
+        this.redactor = new StreamRedactor(ledger);
+    }
+    /**
+     * One write of user code to `stream`, redacted across writes: the tail a
+     * later write could complete into a value waits for it, or for the end of
+     * the tool calls in flight. Held while a config loads. Answers what the
+     * sink did.
+     */
+    write(stream, chunk, callback) {
+        const text = typeof chunk === 'string' ? chunk : this.decoders[stream].write(chunk);
+        if (this.loading > 0) {
+            this.held.push(text);
+            if (callback !== undefined)
+                process.nextTick(callback);
+            return true;
+        }
+        return this.emit(this.redactor.push(text), callback);
+    }
+    /** One line of the server's own, already redacted where it was written; on a line of its own even when user code left one unfinished. */
+    log(line) {
+        this.emit(`${this.atLineStart ? '' : '\n'}${line}\n`);
+    }
+    /** A line of the server's that carries user text (an error nobody caught): redacted and held like what user code writes. */
+    report(line) {
+        this.write('stderr', `${this.atLineStart ? '' : '\n'}${line}\n`);
+    }
+    /**
+     * Runs `load`, a config load that registers the config's secrets, holding
+     * what anyone prints until it ends: the config's top-level code may print
+     * a value before the process knows it is one. Released redacted once every
+     * load in flight succeeded; withheld when one failed, since the secrets of
+     * a config that did not load are unknown.
+     */
+    async withholdDuring(load) {
+        this.loading += 1;
+        try {
+            return await load();
+        }
+        catch (cause) {
+            this.loadFailed = true;
+            throw cause;
+        }
+        finally {
+            this.loading -= 1;
+            if (this.loading === 0)
+                this.releaseHeld();
+        }
+    }
+    /**
+     * Runs one tool call. Once no call is in flight, the tail held for a later
+     * write is released, redacted: user code that printed without a newline is
+     * seen when its call ends, not when the server exits.
+     */
+    async duringCall(call) {
+        this.calls += 1;
+        try {
+            return await call();
+        }
+        finally {
+            this.calls -= 1;
+            if (this.calls === 0 && this.loading === 0)
+                this.emit(this.redactor.flush());
+        }
+    }
+    /** Releases what is still held, redacted; nothing more will follow. Output held for a load still in flight is withheld. */
+    end() {
+        this.write('stdout', this.decoders.stdout.end());
+        this.write('stderr', this.decoders.stderr.end());
+        if (this.loading > 0)
+            this.withhold();
+        this.emit(this.redactor.flush());
+    }
+    releaseHeld() {
+        if (this.loadFailed) {
+            this.withhold();
+            return;
+        }
+        const held = this.held;
+        this.held = [];
+        for (const text of held)
+            this.emit(this.redactor.push(text));
+    }
+    withhold() {
+        const bytes = this.held.reduce((total, text) => total + Buffer.byteLength(text), 0);
+        this.held = [];
+        this.loadFailed = false;
+        if (bytes > 0)
+            this.log(`e2e mcp: [warning] withheld ${bytes} bytes of output printed while a config failed to load: its secrets are unknown, so the output cannot be redacted`);
+    }
+    emit(text, callback) {
+        if (text === '') {
+            if (callback !== undefined)
+                process.nextTick(callback);
+            return true;
+        }
+        this.atLineStart = text.endsWith('\n');
+        return this.sink(text, callback);
+    }
+}

package/dist/mcp/server.d.ts

@@ -7,6 +7,7 @@
  * it the process's and a test hands it pipes.
  */
 import type { Readable, Writable } from 'node:stream';
+import type { McpOutput } from './output.ts';
 import type { McpSessionSummary } from './usage.ts';
 /** The client as it named itself in `initialize`. */
 export interface McpClient {
@@ -19,6 +20,7 @@ export interface ServeOptions {
     readonly configPath?: string | undefined;
     /** The target every session opens on; otherwise a call names one, or the only one is used. */
     readonly target?: string | undefined;
+    /** Whether a session shows its UI when `open_session` does not set `headed`. */
     readonly headed: boolean;
     /** How many sessions may be open at once, from `--max-sessions`. */
     readonly maxSessions?: number | undefined;
@@ -29,6 +31,8 @@ export interface ServeOptions {
     readonly stdout: Writable;
     /** Diagnostics for the operator, normally stderr. */
     readonly log: (line: string) => void;
+    /** What user code in this process prints: held while a config loads, and its unfinished lines released once no tool call is in flight. */
+    readonly output?: Pick<McpOutput, 'withholdDuring' | 'duringCall'> | undefined;
     /** Ends the server from outside: a process signal. */
     readonly signal?: AbortSignal | undefined;
     /** Told once per `open_session`, when its session closes or its open fails, with the client that asked; undefined before `initialize`. */