ADR-003: Transport Abstraction

• Status: Accepted (public ADR; implementation amendments recorded below)
• Date: 2026-05-27
• Deciders: johnny4young

Current implementation: all three transports are implemented. The original decision and matrices below are historical; later amendments in this record describe their evolution. Use the compatibility guide and runtime capability flags for the current supported surface.

Context

Electron Stagewright is an MCP server that drives Electron desktop applications. Before any tool can be written (click, type, snapshot, eval, etc.), the project needs a settled answer to "how does the server actually talk to the running Electron process?"

Three viable mechanisms exist, each with distinct trade-offs:

1. Playwright _electron — Microsoft's experimental wrapper around the Chromium driver. Convenient, well-typed, but marked experimental and could be deprecated. See Playwright MCP PR #1291 for the upstream-deprecation signal that informs this ADR.
2. Raw Chrome DevTools Protocol (CDP) — the stable public protocol that Chrome DevTools itself uses. Lower-level, requires hand-rolling WebSocket + JSON-RPC plumbing, but doesn't depend on any upstream wrapper that could go away.
3. Inject Node Inspector into a running process — best ergonomic for developers (no pre-flag required, attach to an app that's already running) but experimental, platform-dependent, and uses process._debugProcess whose Windows behaviour is less reliable than POSIX.

If the server's tools hardcode any single mechanism, they inherit its limitations forever. If they leave the choice ad-hoc per tool, the plumbing duplicates N times and inconsistencies between tools surface as confusing failures. This ADR locks the contract that every tool dispatches through.

Decision

1. Single contract: ITransport

export interface ITransport {
  readonly id: TransportId // 'playwright-electron' | 'cdp' | 'injector'
  readonly capabilities: TransportCapabilities

  launch(opts: LaunchOptions): Promise<TransportSession>
  attach(opts: AttachOptions): Promise<TransportSession>
  inject(opts: InjectOptions): Promise<TransportSession>
  stop(session: TransportSession, opts?: StopOptions): Promise<void>
  forceKill(session: TransportSession): Promise<void>
}

export interface TransportSession {
  readonly id: SessionId
  readonly transport: TransportId

  evaluate<T>(target: 'main' | 'renderer', body: string, arg?: unknown): Promise<T>
  screenshot(target: WindowRef, opts?: ScreenshotOptions): Promise<Buffer>
  windowsList(): Promise<readonly WindowDescriptor[]>
  readonly ipc: IpcChannel
  readonly console: ConsoleStream

  /** Idempotent — calling twice does not throw, does not double-free. */
  dispose(): Promise<void>
}

Every tool dispatches through ITransport. The transport implementation can change without touching tools, plugins, or examples; the contract is the seam.

2. Capability matrix

Every transport declares its capabilities up front via a TransportCapabilities record. The dispatcher inspects the matrix BEFORE invoking a method and refuses unsupported operations with TRANSPORT_UNSUPPORTED (registered code from the central error registry) instead of crashing partway through the SDK with a vague Playwright/CDP error.

export interface TransportCapabilities {
  readonly canLaunch: boolean
  readonly canAttach: boolean
  readonly canInject: boolean
  readonly canIntercept: boolean // network / IPC mid-flight modification
  readonly canControlClock: boolean
  readonly supportsMainEval: boolean
  readonly supportsRendererEval: boolean
}

A helper assertCapability(transport, capability) is exported alongside the interface so tool handlers can refuse-when-unsupported with a single line.

3. Three implementations

PlaywrightElectronTransport ships as the only fully-implemented transport in this slice. It uses Playwright's experimental _electron.launch() API loaded via dynamic import so the playwright peer dependency stays optional: consumers can install @electron-stagewright/core without playwright and still import the package; only invoking launch() surfaces a TRANSPORT_UNSUPPORTED error with a clear remediation hint.

Deviation from the original scope: the design draft assumed PlaywrightElectronTransport would also support canAttach: true. After investigation, Playwright's _electron does NOT expose a public attach API — it only exposes launch. Attach behaviour is delegated to CDPTransport (which connects to an already-running app via its CDP endpoint). The Playwright transport now declares canAttach: false and its attach() method rejects with TRANSPORT_UNSUPPORTED. The capability matrix above reflects this corrected reality.

CDPTransport and InjectorTransport ship as stubs in this slice. Their constructors succeed, their capability matrices are declared honestly, and every method rejects with a registered error code (TRANSPORT_UNSUPPORTED when the capability matrix already refuses; NOT_IMPLEMENTED when the capability is claimed but the body is deferred). The point of shipping the stubs now is to force every downstream slice to honour the contract — tools cannot reach into transport-specific behaviour because there is no transport-specific behaviour to reach into yet.

4. CDP connection pool (design captured, implementation deferred)

When CDPTransport's body lands in a future slice, the connection pool design adopted from prior art (laststance/electron-mcp-server/src/utils/cdp-pool.ts) is:

• Multiplexed WebSocket per target. One socket connection per Electron target (main process, each renderer); messages from all in-flight calls share the same socket via per-target queueing.
• Pending-message map keyed by request ID. CDP uses id field on every JSON-RPC envelope; the pool keeps a Map<id, { resolve, reject }> so responses route back to their callers without races.
• Per-method timeout handles. Default 30s with caller-overridable timeoutMs. Timer is cleared on response or rejection.
• enabledDomains: Set<string> per target. CDP requires explicit Page.enable, Runtime.enable, DOM.enable before the corresponding events fire. The pool tracks which domains are already enabled so subsequent calls skip the redundant enable.
• awaitPromise: true option. Runtime.evaluate accepts a flag that waits for Promise resolution before returning. Tools that evaluate async code (most of them) pass awaitPromise: true through the pool's evaluate helper.

None of this ships in the current slice; the design lives here so the CDP-implementation slice has a contract to honour.

5. Eval payload validation lives in the dispatcher, not the transport

The transport's evaluate() method does NOT validate the body string against the eval blocklist (see ADR-006). The dispatcher invokes routeByOperationType(operationType, payload) BEFORE calling transport.evaluate(), and operationType: 'eval' flows through validateEvalContent which screens the keyword blocklist. Direct callers (tests, application code) that bypass the dispatcher inherit responsibility for validating untrusted payloads.

The current evaluate() implementation wraps the body in a function string using positional parameter names (async (electronApp, arg) => { ${body} } for main, async (arg) => { ${body} } for renderer). A malicious or malformed body string CAN break out of the wrapper. The robust protocol (AST inspection, structured eval messages instead of string concatenation) lands with the eval-tool ADR and the threat-model ADR. The string wrapper here is intentionally minimal.

Rationale

Why three implementations behind one interface

A single implementation locks the project to one vendor's roadmap. The Playwright deprecation signal makes this concrete: if Microsoft removes _electron, the project either rewrites every tool against CDP or dies. With three implementations behind ITransport, the dispatcher can swap implementations transparently. The cost is one interface definition + capability matrix; the benefit is multi-year survivability.

Why a capability matrix instead of dynamic feature detection

Boot-time matrix inspection is cheap (a property read) and lets the dispatcher refuse-when-unsupported at the first opportunity. Dynamic feature detection (try the call, catch the error, fall back) burns at least one round-trip per failure and surfaces transport-specific exceptions to tools. The matrix is also self-documenting: a contributor reading a transport sees its declared lifecycle and operation support before following any method body.

Why dynamic await import('playwright')

playwright is declared as an OPTIONAL peer dependency. A consumer installing @electron-stagewright/core and NEVER using PlaywrightElectronTransport should not be forced to install Playwright. Static import at module-load time crashes the package import for those consumers; dynamic await import('playwright') defers the failure until the first launch() call, at which point the failure is structured (TRANSPORT_UNSUPPORTED with an install-instruction hint) instead of a raw module-not-found crash.

Why ship the CDP / Injector stubs now

Two reasons:

1. The capability matrix becomes load-bearing immediately. Downstream slices that need attach (the future "attach-without-restart" Brecha A work) will read cdp.capabilities.canAttach === true and consume that as a contract. Shipping the stubs now means slices can be planned against the real capability matrix instead of pseudo-code.
2. The seams are the security surface, not the bodies. Once routeByOperationType + assertCapability exist as the single entry points, tool implementations cannot accidentally bypass them. Shipping the bodies as stubs that throw NOT_IMPLEMENTED is more honest than not shipping the classes at all — the capability matrix lies if it claims canAttach: true and the class doesn't exist.

Why dispose() is idempotent

The dispatcher may call dispose() during normal shutdown AND during error recovery. A non-idempotent dispose() produces double-free crashes in the recovery path. The contract is documented at the interface level; the Playwright session honours it via a disposed: boolean flag; the test fake demonstrates the same shape.

Alternatives considered

Consequences

• Every tool dispatches through ITransport. Tools cannot import playwright directly; they cannot reach into a transport-specific method.
• Adding a new transport (e.g. WebDriverTransport, ExtensionHostTransport) means implementing ITransport and declaring a capability matrix — no other changes required to existing tools.
• The capability matrix is the API surface tools depend on. Adding a new capability (e.g. canSendNotification) is a backwards-incompatible change to TransportCapabilities — every transport must update its declared matrix in the same PR.
• The playwright peer dependency stays optional. Consumers without Playwright cannot use PlaywrightElectronTransport.launch() but can still import the package and use CDPTransport once its body lands.
• dispose() is idempotent at the contract level. Implementations that fail to honour this are buggy; the test fake demonstrates the shape.
• The dispatcher is the single chokepoint for eval validation (via routeByOperationType from ADR-006). Transport implementations do NOT validate eval payloads on their own; direct callers bypassing the dispatcher inherit the responsibility.
• Eval tools now ship behind --allow-eval with dispatcher-level keyword validation. A future threat-model slice can still replace the minimal string wrapper with structured messages, AST inspection, and richer audit logging.

Amendment (2026-05-28): Interaction surface

The original contract covered observation (evaluate, screenshot, windowsList) but no real user input. Driving an Electron app requires click/type/hover/drag/scroll, so the contract is extended additively. The seam is unchanged — tools still dispatch through ITransport / TransportSession; this amendment adds methods, it does not alter the existing ones.

New capability flag

TransportCapabilities gains an eighth flag:

/**
 * The transport can perform real user input (click, type, hover, drag, …) on a
 * renderer element. A transport declaring this `false` rejects those methods.
 */
readonly supportsInteraction: boolean

Per-transport values:

Adding a capability flag is a backwards-incompatible change to TransportCapabilities (every transport must update its matrix in the same change), exactly as the original Consequences section anticipated.

New session methods

TransportSession gains nine methods, all operating on the active/default window with real user input: click, fill, hover, press, selectOption, setChecked, setInputFiles, dragTo, and scroll. Three option types support them:

• InteractionOptions { force?, timeoutMs? } — common actionability controls. The Playwright transport maps these onto its action options as { force, timeout }, omitting absent keys (required under exactOptionalPropertyTypes).
• PressOptions extends InteractionOptions { selector? } — press focuses selector first when given, otherwise presses against the active keyboard.
• ScrollOptions { selector?, dx?, dy?, timeoutMs? } — scroll centres selector into view when given, otherwise dispatches a wheel delta.

No-match must be observable

Eight of the nine methods delegate to Playwright actions that already reject when the selector matches nothing. scroll's into-view path runs in the renderer (the minimal page surface intentionally does not expose Playwright locators), so it explicitly reports whether the element was found and rejects with SELECTOR_NO_MATCH on a miss. A silent success here would let the tool layer report a phantom scroll it cannot diagnose — every interaction method surfaces a missing target uniformly.

Scope of this slice

This amendment ships the contract plus the Playwright implementation only. The agent-facing interaction tools (and the ref → [data-sw-ref="…"] resolution they perform before reaching the transport) land in the following slice; the CDP/Injector bodies remain deferred and continue to reject with NOT_IMPLEMENTED once their sessions exist.

Follow-up (tool layer): two additive surface refinements

The tool-layer slice that builds on this amendment added two backwards-compatible methods to the interaction surface, both implemented in PlaywrightElectronTransport and recorded by the test fake:

• ClickOptions extends InteractionOptions { button?, clickCount? } — click now carries an optional pointer button (left/right/middle) and click count, so one method covers right-click (context menus) and double-click (click-to-edit) without separate transport methods.
• typeText(text, opts?: PressOptions) — real per-character keystrokes (each fires keydown/keypress/input/keyup), distinct from fill (which sets .value and fires a single input event). For inputs with per-keystroke handlers (editors, autocompletes). Focuses opts.selector first when given; otherwise types into the active element.

Both are additive — existing callers are unaffected, and supportsInteraction already gates them. The CDP/Injector stubs declare supportsInteraction: false and gain no method bodies.

The tool layer also established a shared resolver (ref/selector → one selector), a bounded per-action timeout (default 5s, clamp 30s), a raw-throw → registered-code classifier (mirroring the launch-error diagnoser, e.g. a Playwright "element is not enabled" message → ELEMENT_DISABLED), a ref-freshness guard against the stored snapshot, and similar_refs candidates sourced from a fresh live walk on a miss.

Amendment (2026-05-30): Console-output buffer

The observation tool slice (electron_screenshot + electron_console_logs) needed the transport to surface renderer console output. Screenshots already had a method (screenshot(window, opts)); console output did not, because console messages are events — they arrive asynchronously while the app runs, and a query-time pull cannot retroactively observe a console.log that already fired. So the contract gains a small capture buffer.

New session method

interface ConsoleEntry {
  readonly type: string // 'log' | 'info' | 'warning' | 'error' | 'debug' | ...
  readonly text: string
  readonly timestamp: number // epoch ms
  readonly location?: { url?: string; line?: number; column?: number }
}

interface ConsoleLogsResult {
  readonly entries: readonly ConsoleEntry[]
  readonly overflowed: number // count of older entries the buffer dropped
}

// on TransportSession:
consoleLogs(): Promise<ConsoleLogsResult>

Capture model

• PlaywrightElectronTransport subscribes to page.on('console') on the launch-time first window, synchronously in the session constructor (the launch path resolves firstWindow() once and passes the page in, so console capture adds no extra firstWindow() round-trip).
• The buffer is a bounded ring (cap 1000). On overflow the oldest entry is shifted out and an overflowed counter increments, so electron_console_logs can tell the agent the view is incomplete rather than silently truncating (ADR-007 — surface staleness, never fake completeness).
• Entries are plain JSON-serialisable records (no Map/Set/Date), consistent with the agent-payload invariant. Playwright's location.lineNumber/columnNumber are normalised to line/column.

Scope and deferrals

• Single window only. Only the launch-time first window's console is captured; multi-window console aggregation is out of scope for this slice (no demand yet, and it would require tracking page lifecycle across switch_window).
• Post-dispose behaviour. consoleLogs() calls requireRunning() and rejects with NOT_RUNNING after the session is disposed — contract-consistent with the other read methods. A crash does not dispose the session, so the in-memory buffer survives a renderer crash for post-mortem inspection; an explicit stop/force_kill clears it. (Product decision: keep the buffer ephemeral, tied to session lifetime.)
• Historical scope: the CDP/Injector stubs gained no console capture in this amendment because their sessions did not exist yet. The 2026-06-10 status update records the current CDP/Injector capture support.

dialog_handler (the other event-driven surface originally bundled with this slice) is deferred to its own follow-up so this console-buffer amendment ships isolated from a page.on('dialog') amendment.

Amendment (2026-05-31): Dialog handling

The deferred follow-up to the console-buffer amendment. Native JS dialogs (alert / confirm / prompt / beforeunload) block the renderer until something answers, so — like console output — they cannot be observed by a query-time pull, and unlike console they require an active response. The contract gains a small forward-looking auto-responder plus a capture buffer.

New types and session methods

type DialogAction = 'accept' | 'dismiss'
type DialogType = 'alert' | 'confirm' | 'prompt' | 'beforeunload'

interface DialogPolicy {
  readonly action: DialogAction // default for any unmatched dialog
  readonly promptText?: string // submitted to prompt() when its effective action is accept
  readonly perType?: Partial<Record<DialogType, DialogAction>> // per-kind overrides; falls back to action
  readonly oneShot?: boolean // resolve exactly one dialog, then revert to the dismiss default
}

interface DialogEvent {
  readonly type: string
  readonly message: string
  readonly action: DialogAction // how the responder resolved it
  readonly defaultValue?: string // prompt()'s default, when non-empty
  readonly promptText?: string // text submitted to a prompt() accept
  readonly timestamp: number // epoch ms
}

interface DialogEventsResult {
  readonly entries: readonly DialogEvent[]
  readonly overflowed: number
  readonly policy: DialogPolicy // the policy currently in effect
}

// on TransportSession:
setDialogPolicy(policy: DialogPolicy): Promise<void>
dialogEvents(opts?: { clear?: boolean }): Promise<DialogEventsResult>

Capture and response model

• PlaywrightElectronTransport subscribes to page.on('dialog') on the launch-time first window, synchronously in the session constructor, alongside the console listener (the launch path resolves firstWindow() once and passes the page in, so dialog capture adds no extra round-trip).
• Critical invariant: attaching a dialog listener disables Playwright's own auto-dismiss. Once a listener exists, the listener MUST resolve every dialog (accept/dismiss) or the renderer hangs forever. The session defaults its policy to dismiss, so dialogs are always resolved — even before the agent arms anything — and the app never hangs.
• The handler reads type/message/defaultValue before calling accept/dismiss (which can invalidate the handle), resolves per the active policy, and records the event regardless of whether accept/dismiss throws (an already-handled or closed dialog is still worth recording for post-mortem).
• oneShot reverts the policy to the safe dismiss default after a single dialog, so a lingering accept cannot silently confirm a later, unexpected (possibly destructive) dialog.
• The buffer is a bounded ring (cap 200) with an overflowed counter (dialogs are far rarer than console messages, so a smaller cap than the console buffer's 1000). Overflow surfaces to the agent rather than silently truncating (ADR-007).
• Entries are plain JSON-serialisable records (no Map/Set/Date), consistent with the agent-payload invariant.

Scope and deferrals

• Single window only. Same boundary as the console buffer — only the launch-time first window's dialogs are captured.
• Post-dispose behaviour. setDialogPolicy() / dialogEvents() call requireRunning() and reject with NOT_RUNNING after dispose — contract-consistent with consoleLogs(). The buffer survives a renderer crash (the session is not disposed) for post-mortem; an explicit stop/force_kill clears it.
• No new capability flag. Like the console buffer, dialog capture rides the session. Historical scope: the CDP/Injector stubs gained no dialog handling in this amendment because their sessions did not exist yet; the 2026-06-10 status update records the current CDP support and Injector boundary.
• prompt() caveat. Electron does not implement renderer window.prompt() (it is a no-op returning null and fires no dialog), so the real-Electron smoke exercises confirm + alert; prompt-text handling is validated through the transport fake in unit tests. The contract still carries promptText for transports/runtimes that do surface prompts.

Related decisions

• ADR-001 — Naming and License. Transports ship under MIT, no contributor agreement needed.
• ADR-002 — Runtime and Language. The dynamic await import('playwright') idiom and the strict-plus TypeScript profile (noUncheckedIndexedAccess, exactOptionalPropertyTypes) directly shape this slice.
• ADR-006 — Error Code Registry and Agent-UX Response Envelope. Transports consume codes (TRANSPORT_UNSUPPORTED, NOT_IMPLEMENTED, CDP_DISCONNECTED, INJECT_FAILED, LAUNCH_TIMEOUT, REF_NOT_FOUND, NOT_RUNNING); the mirror test enforces every literal usage matches a registered key.
• ADR-007 — Agent-native UX principles. The capability matrix is the seam that lets tool descriptions (Principle 1) cite the failure codes they can raise without leaking transport-specific failure modes.
• ADR-004 — Plugin model; plugin-provided tools and codes register alongside the same transport/tool contracts.
• Eval tools — already shipped behind --allow-eval; the transport contract remains the execution seam.
• Threat-model ADR (forthcoming) — will harden eval validation beyond the keyword blocklist already shipped in ADR-006.

References

• packages/core/src/transports/types.ts — the contract itself.
• packages/core/src/transports/capabilities.ts — assertCapability helper.
• packages/core/src/transports/playwright-electron.ts — first concrete implementation.
• packages/core/src/transports/cdp.ts — CDP implementation plus pool design history captured in this ADR.
• packages/core/src/transports/injector.ts — Node-inspector inject/attach implementation.
• packages/core/tests/transports.test.ts — table-driven capability-vs-method drift detection.
• Playwright _electron documentation — upstream API surface.
• Chrome DevTools Protocol — the public protocol CDPTransport will speak.
• Playwright MCP PR #1291 — the deprecation signal that motivates this abstraction.

Status Update — 2026-06-10

The CDP transport's connection pool and the Injector transport's Node-inspector attach/inject paths are now implemented. Earlier sections remain the historical record of the contract-first slice that shipped the stubs; the current implementation status is below.

• packages/core/src/transports/cdp-connection.ts realises the pool design this ADR captured: one WebSocket per target, a pending map keyed by request id, per-method timeouts (new registered code CDP_TIMEOUT), an enabled-domain cache, and awaitPromise evaluation. The socket is created through an injectable factory; the default is Node's global WebSocket, so the core gains no runtime dependency.
• CDPTransport.attach resolves the browser endpoint from a cdpUrl or host:port (/json/version + /json/list), pools per-page-target connections lazily, aggregates console (Runtime.consoleAPICalled) and dialog (Page.javascriptDialogOpening) capture across every target, supports screenshots and renderer/main Runtime.evaluate, implements core interaction through Input.dispatch* / DOM.setFileInputFiles, and runs a bounded Browser.close stop that escalates to SIGKILL when the attach supplied a pid.
• InjectorTransport triggers or reuses the Node inspector, polls the bounded /json/list discovery path, verifies the discovered target title belongs to the requested pid (and verifies process.pid for direct cdpUrl attaches with a supplied pid), supports main-process Runtime.evaluate, window listing, console capture, and a bounded graceful quit. It still does not expose renderer eval or interaction; those remain CDP/Playwright responsibilities.
• ITransport.stop now returns a StopResult ({ escalated }): every transport's graceful stop is bounded and escalates to SIGKILL rather than wedging on a hung app — the session is always released with the process reaped, never orphaned without a handle.
• The Playwright transport additionally attaches console/dialog capture to EVERY window (the window event), attributes buffered entries by windowId, and recovers the active window from the known list before blocking on a new window event after modal-induced handle loss.

Status Update — 2026-06-16: Network capture seam (canIntercept's first consumer)

The canIntercept capability, dormant since this ADR reserved it, gains its first consumer (see ADR-016). TransportSession is extended with an ARMED network-capture seam — startNetworkCapture, networkEvents, stopNetworkCapture — alongside the always-on console/dialog buffers.

• The Playwright transport implements the seam via page.on('requestfinished'|'requestfailed') (renderer traffic) and flips canIntercept from false to true — capture is the observe half of "intercept". The listeners attach next to the console/dialog ones (current + future windows) and stay inert until a filter is armed.
• The CDP transport declares canIntercept: false for now: its Network domain could serve capture, but the seam is not wired, and a capability that now has a consumer (the plugin gate) stays honest rather than advertising methods that reject at runtime. The flag flips to true when the CDP seam lands. Its three seam methods still throw NOT_IMPLEMENTED for a direct caller that bypasses the gate (distinct from its canControlClock, which stays aspirational-true while it has no consumer).
• The injector transport keeps canIntercept: false (no renderer network).

So the plugin's capability gate refuses both CDP and injector sessions with network.UNSUPPORTED (naming the Playwright transport), while NOT_IMPLEMENTED remains the contract-level signal for a direct caller that ignores the capability. Capture rides this seam rather than the eval seam (ADR-010's approach) because protocol-level network is invisible to evaluate, and so it is NOT --allow-eval gated.

Status Update — 2026-06-18: canIntercept's second consumer (CDP network seam)

The seam reserved above is now wired on the CDP transport too, so canIntercept flips from false to true on CDP and the capability is honest on both attach-mode and launch-mode (see ADR-016).

• Capture + bodies ride the CDP Network domain (Network.enable, the requestWillBeSent → responseReceived → loadingFinished/loadingFailed correlation, Network.getResponseBody); the inert-until-armed listener pattern matches the Playwright transport (the listeners attach per pooled page connection in #attachCapture; Network.enable/disable toggles on arm/stop).
• Stubbing rides the Fetch domain (Fetch.enable + Fetch.requestPaused → fulfill/fail/ continue). The five seam methods are fully implemented — none throws NOT_IMPLEMENTED — so canIntercept: true is honest, not aspirational.
• Scope is renderer page-target traffic, the same as Playwright (not the main process's net module). The injector transport keeps canIntercept: false (no renderer network).

The canIntercept capability now has TWO honest implementers; it is the per-transport gate the network plugin reads, and a transport advertises it only once the whole seam is wired.

Status Update — 2026-06-19: canControlClock's first consumer (clock seam)

The canControlClock capability, reserved in this ADR's matrix and previously declared without a consumer (the CDP transport even advertised it aspirationally true), gains its first consumer: a clock seam on TransportSession — installClock / setFixedTime / setSystemTime / advanceClock / runClockFor / pauseClockAt / resumeClock — driven by the clock plugin (see ADR-017).

• The Playwright transport implements the seam via page.clock (its fake-timer controller over the renderer's Date / setTimeout / setInterval) and flips canControlClock from false to true.
• The CDP transport flips its aspirational true to honest false: Emulation.setVirtualTimePolicy cannot satisfy the full seam (notably resume-to-real), so advertising the capability would be the trap this ADR warns against. Its seam methods reject NOT_IMPLEMENTED; a CDP clock increment is a deferred follow-up.
• The injector transport keeps canControlClock: false (no renderer clock).

This is the same lesson canIntercept taught, applied proactively: a capability is advertised true only where the whole seam is honestly wired, and an aspirational true (CDP's) is corrected to false the moment the capability gains a real consumer.

Status Update — 2026-06-19: canAccessStorage's first consumers (storage seam)

A canAccessStorage capability is added to TransportCapabilities and immediately consumed by a storage seam on TransportSession — getCookies / setCookie / clearCookies / storageSnapshot (plus the types StorageCookie / CookieFilter / StorageOrigin / StorageSnapshot) — driven by the storage plugin (see ADR-018). Unlike canControlClock, this capability has TWO honest implementers from the start:

• The Playwright transport implements the seam via the page's BrowserContext (cookies / addCookies / clearCookies / storageState) and declares canAccessStorage: true.
• The CDP transport implements it via the Storage / Network domains (cookies) plus a best-effort DOMStorage read for the snapshot's localStorage half, and also declares canAccessStorage: true. That is honest because every seam method is wired and resolves (the best-effort localStorage is a documented partial within the snapshot, not a rejecting method).
• The injector transport keeps canAccessStorage: false (no renderer storage).

This is the inverse of the clock lesson and the reason the matrix carries canIntercept-style nuance: where the clock seam could only be honestly wired on Playwright, the storage seam is honestly wired on both observe-capable transports, so both advertise true — and the one partial (CDP localStorage) is documented rather than hidden behind a rejecting method.

Status Update — 2026-06-19: canAccessNativeUI's first consumer (native-UI seam)

A canAccessNativeUI capability is added to TransportCapabilities and consumed by a native-UI read seam on TransportSession — getApplicationMenu() (plus the types NativeMenu / NativeMenuItem) — driven by the native-UI plugin (see ADR-019). Like the clock seam, it is Playwright-only:

• The Playwright transport implements it via electronApp.evaluate running a fixed serializer over Menu.getApplicationMenu() in the Electron main-process Node context, and declares canAccessNativeUI: true.
• The CDP transport declares canAccessNativeUI: false: its endpoint exposes renderer targets only (see the 2026-10-22 status update), with no Electron Menu module, so it cannot reach the main-process menu. The seam method rejects NOT_IMPLEMENTED.
• The injector transport keeps canAccessNativeUI: false (capability-honest stub).

The lesson is the same the matrix keeps teaching: a capability is advertised true only where the whole seam is honestly wired. The application menu lives in the main-process Node context, which only the Playwright electronApp.evaluate path reaches, so only it advertises true.

Status Update — 2026-06-19: LaunchOptions.instrumentNative

LaunchOptions gains an optional instrumentNative flag (default off). When set on the Playwright launch transport, the transport wraps the app's main entry with fixed hooks installed before the app runs, so native state created at startup (the system Tray, and notifications shown in app.whenReady()) is observable — see ADR-020 for the mechanism and threat reasoning. It requires a main/appPath entry (executablePath-only launches cannot be wrapped). It is a launch-transport-only opt-in; CDP/injector cannot wrap a running app's entry, so the consuming seam (getTrays and invokeTrayEvent) rejects NOT_IMPLEMENTED there. The notification-capture seam adopts the launch-installed t=0 hook when present, so on an instrumented session it also returns startup notifications (tagged beforeArm).

The native-UI seam also gains invokeTrayEvent(id, event) (the tray analog of invokeApplicationMenuItem, returning a TrayInvokeResult): it acts on the same launch-time tray registry, so like getTrays it resolves null on a session launched without instrumentNative and is Playwright-only (CDP/injector reject NOT_IMPLEMENTED). See ADR-019's tray-invocation Status Update.

Status Update — 2026-06-22: supportsRendererEval gains a plugin consumer (per-key storage)

supportsRendererEval previously had a single consumer — the core electron_eval_renderer tool. The storage plugin's new per-key localStorage / sessionStorage tools (ADR-018 Status Update) become its first plugin consumer: they reach TransportSession.evaluate('renderer', …) directly with a fixed source string, so they require supportsRendererEval (and the operator's --allow-eval=renderer grant). No new seam method or capability is added — this consumes the existing evaluate seam and supportsRendererEval flag. Both observe-capable transports already advertise it: the Playwright transport via page.evaluate, the CDP transport via Runtime.evaluate against a page target; the injector keeps supportsRendererEval: false, so the per-key tools return storage.UNSUPPORTED there — the same two-implementers-plus-injector shape the storage seam itself has.

Status Update — 2026-07-10: active window selection and process-preserving detach

TransportSession now carries two lifecycle operations that make multi-window sessions explicit without coupling tools to a concrete transport:

activateWindow(target: WindowRef): Promise<WindowDescriptor>
detach(): Promise<void>

• Active-window selection is a Stagewright target, not an OS-focus promise. electron_switch_window resolves a WindowRef through the common selector precedence, then subsequent renderer-implicit reads and interactions use that selected window. Playwright stores the selected Page; CDP stores the selected page target. If that target closes, both deterministically fall back to the first live window. Console, dialog, and network buffers continue to preserve each event's source windowId, so changing the active target never rewrites event attribution.
• No new capability flag is needed. The method itself is the narrow seam: Playwright and CDP implement it, while Injector rejects it with the existing TRANSPORT_UNSUPPORTED signal because it has no renderer interaction target. This avoids advertising a broad capability that is meaningful only to one lifecycle command.
• Detach is ownership-aware. CDP and Injector sessions were attached to a running process, so their detach() closes transport sockets through their existing idempotent dispose() paths and never sends Browser.close, Electron quit, or SIGKILL. A Playwright launch session rejects detach with TRANSPORT_UNSUPPORTED: its application handle owns the process and closing it is indistinguishable from stopping it. The session manager deletes a successfully detached session and restores it if the transport disconnect fails.

The real-Electron suite covers switching a two-window Playwright fixture, deterministic recovery after the selected window closes, and CDP attach followed by detach while the Electron process remains alive.

Status Update — 2026-07-14: target-owned Electron runtime selection

Launch now accepts an operator-bounded runtime: "project" mode (ADR-024). The lifecycle tool resolves the target Electron binary from the server's configured --app-root, then passes its canonical absolute path through the existing LaunchOptions.executablePath field to the Playwright transport. This is deliberately a tool-layer selection policy, not a new transport capability: the transport still receives one already-authorized executable and owns the same launch mechanics.

executablePath remains authoritative when the caller explicitly provides it, preserving the existing packaged-app path and avoiding a surprise runtime override. At the time of this amendment, CDP and Injector were unchanged: they attached to existing processes and did not select a launch binary. The packaged-CDP amendment below supersedes that statement for executable-only launches.

Status Update — 2026-07-27: fuse-aware Playwright launch preflight

Playwright's Electron transport always requires the main-process Node inspector channel (--inspect=0), including when LaunchOptions.executablePath selects a custom Electron runtime for a main entry. The lifecycle tool inspects that selected binary's Electron fuse wire before invoking Playwright. A positively disabled or removed EnableNodeCliInspectArguments fuse returns FUSES_BLOCK_LAUNCH with packaged-CDP, CDP-attach, and development-build recovery actions, instead of spawning a process whose failed inspector handshake can surface as an opaque transport close.

This remains tool-layer compatibility policy rather than a capability flag: the Playwright transport can launch compatible binaries, while fuse state belongs to each selected executable. Inspection is read-only, cached by executable path, and fail-open for unknown/non-Electron wires; only positive incompatibility evidence blocks process creation. Executable-only packaged launches and CDP attach are unaffected because they use Chromium's remote-debugging endpoint rather than the Node inspector channel.

Status Update — 2026-07-27: owned packaged-app launch over CDP

CDPTransport.canLaunch becomes honestly true for one deliberately narrow shape: LaunchOptions.executablePath with no appPath/main. The lifecycle tool treats that as a packaged app and requires the CDP transport by id; a main-based development launch continues to select the first generic canLaunch transport (Playwright).

The CDP launch implementation owns the whole repeated consumer sequence:

1. reserve a currently-free IPv4 loopback port;
2. spawn the executable with transport-owned --remote-debugging-address=127.0.0.1 and --remote-debugging-port;
3. poll /json/version and /json/list with bounded per-probe and total budgets until a page target exists;
4. connect through the existing pooled CDP attach path; and
5. retain child ownership so stop waits for real process exit within the graceful-close budget, escalates to SIGKILL when necessary, and briefly waits for the killed child to be reaped.

Caller-supplied remote-debugging switches are refused because they would make endpoint ownership and cleanup ambiguous. Failed discovery or connection reaps the child. A launch-owned CDP session rejects detach just like a Playwright launch session; an ordinary CDP attach remains process-preserving on detach.

LaunchOptions.credentialStore makes the packaged automation trade-off explicit. testing (default) adds --use-mock-keychain on macOS or --password-store=basic on Linux unless the caller already selected a Linux store; system adds neither. Testing mode prevents OS credential prompts from wedging unattended startup, but cannot validate genuine OS-backed safeStorage sealing.

Status Update — 2026-10-02: failure-safe attachment and connection cleanup

Session initialization now fetches the initial window list before publishing a handle. If setup fails, launch stops its owned process, while attach and inject only detach their transport connection. A cleanup error preserves the original failure and cannot leave an unaddressable session in the manager. Explicit stop retains its existing process-termination behavior.

CDP and Inspector discovery reject HTTP redirects and validate discovered WebSocket URLs against the same loopback policy as caller-supplied endpoints. Browser and renderer discovery are both covered. Inspector discovery labels select candidate targets; when a pid is supplied, the connected inspector must also report that pid before the session is returned. This narrows accidental target mismatches within the existing trusted-local-process model; it is not endpoint authentication.

The CDP client ignores malformed frames without consuming pending calls or their timeout handles, and stops delivering events after close. Page connections completing after browser disconnection are closed instead of being added to the pool. A disconnected session refuses operations that reach the app, keeps already-buffered console, dialog, and network diagnostics readable, and preserves the owned-process cleanup path.

Status Update — 2026-10-15: attach reconnect and launched-session drops

A CDP attach session whose browser socket drops now reconnects lazily: the next call that reaches the app re-discovers the browser endpoint through /json/version (falling back to the previous WebSocket URL), with at most three attempts inside a 10 s budget. Concurrent calls share one reconnect. It then re-selects the previously selected target by id, or by URL and title when the app restarted with new target ids, and re-opens the page pool so console, dialog, network capture, and stubs re-arm. Buffered diagnostics never trigger a reconnect.

TransportSession gains an optional onReconnect(listener). The session manager forwards it for registered sessions, and the server clears that session's stored snapshots so refs from before the reconnect are never reused.

Launched sessions are not reconnected. A packaged-CDP launch whose socket drops, and a Playwright launch whose ElectronApplication emits close, reject app-touching calls with the non-retryable SESSION_DISCONNECTED (ADR-006) while keeping buffered diagnostics readable; electron_stop still releases them.

Status Update — 2026-10-22: no main eval over CDP; inject finds Electron's inspector

Live checks on Electron 42 showed that the CDP supportsMainEval: true above was never real. The --remote-debugging-port endpoint lists renderer targets only, and Runtime.evaluate on the browser endpoint fails with "'Runtime.evaluate' wasn't found". The fake CDP server in the unit tests answered it anyway, so the gap went unnoticed. CDPTransport now declares supportsMainEval: false: main evaluation rejects with TRANSPORT_UNSUPPORTED, the IPC plugin refuses through its capability gate, and electron_info reports null versions and app fields instead of failing. Reaching the main process from an attach session would need the Node inspector next to the CDP endpoint, which fused packaged apps usually disable; that is a separate decision.

Two injector fixes came out of the same checks:

• Electron's main inspector is titled electron/js2c/browser_init, without the [pid] label plain Node uses, so pid matching by title rejected every Electron app. The injector now tries targets labelled with the pid first, then unlabelled ones, and keeps the first whose inspector reports that pid. A target labelled with another pid is never contacted.
• Main evaluation now receives the electron module as electronApp (also arguments[0]) and the JSON arg, the same contract as the Playwright launch transport, so electron_info and the IPC plugin's main-process bodies run on inject sessions too.

Status Update — 2026-10-22: reload seam

TransportSession gains reload(target, { ignoreCache }), which issues Page.reload for one window and resolves once the reload is issued, not when the new page is ready. The Playwright transport sends it over a per-page CDP session (the same route it uses to label root surfaces); the CDP transport sends it on the page target's connection; the injector rejects it with TRANSPORT_UNSUPPORTED, since it has no renderer. electron_reload builds on it: it tags the current document, waits until a new document replaces it, then applies the launch readiness check (now shared in tools/lifecycle/ready.ts, which also retries through a navigation).

Status Update — 2026-10-22: setWindowSize seam

TransportSession gains setWindowSize(target, { width, height, content }), which resizes one native window and resolves once its size settles, with the outer and content sizes and, where the transport can read them, the window's minimum and maximum sizes. The Playwright transport finds the BrowserWindow from the page's DevTools target id and the injector by BrowserWindow id; both leave kiosk, fullscreen or maximized state first (waiting for the window manager) and call setSize / setContentSize in main. The CDP endpoint has neither a main process nor the Browser window domain, so the page calls window.resizeTo, which Electron applies to the native window (clamped by its limits) unless the app cancels content-bounds-updated; it cannot report the limits. Blink keeps reporting the requested outer size for a while after the browser applied the real one, while the inner size is real from the resize event on, so the page waits for that event and derives the outer size from the inner one and a frame measured before its first resize. electron_set_window_size builds on it.

Status Update — 2026-10-29: credential-store policy for development launches

LaunchOptions.credentialStore now applies to main-based Playwright launches too, with the same testing default. A development launch used to reach the real macOS Keychain: after an Electron upgrade the new binary is not on the "Electron Safe Storage" item's access list, macOS shows an access prompt, and the main process blocks before its first window, so the launch ended in LAUNCH_TIMEOUT with nothing pointing at the cause. Both transports now share one helper that adds --use-mock-keychain on macOS or --password-store=basic on Linux unless the caller already passed that switch, and credentialStore: "system" still adds neither. The LAUNCH_TIMEOUT hint names a main process blocked on an OS prompt or startup dialog as the usual cause.