dev, start, and preview stream one schema-1 frame per lifecycle transition. Each frame is a complete result envelope on its own line.
Turning the stream on
The stream keys off theEXTENSION_OUTPUT environment variable. Set it to json or ndjson and frames own stdout:
Frame statuses
Every frame’s
value carries the session identity: command, browser, distPath, pid, port, plus readyPath, eventsPath, runId, instanceId, and toolchainVersion when known.
failed, usage, and stopped are terminal. A terminal frame means that the process is ending, and the stream writes nothing after it, so stop reading at the first one. Every other ok: false frame leaves the session running. When the CLI knows the remedy for the code, a failed or usage frame carries it as hint.
Only those three end the stream. A reader ignores a status it does not know and keeps reading, so a status added in a later release never stops it.
From the release after 4.2.0, the two reload failures that the terminal reports, a compile the extension never confirmed and an extension that has not come back, also arrive as a warning frame with W_RELOAD_NOT_APPLIED. The terminal text carries no code.
A run refused before the session begins sends one failed frame and no starting frame. A missing manifest, a config file that fails to load, and a remote URL with no usable archive all end that way.
Compile failures
Acompile-failed frame carries the compiler output inside value.output, so you never scrape stdout. The output is ANSI-stripped and capped at 2000 characters. When the cap cuts it, the frame sets truncated: true.
The first failure of a session uses code E_FIRST_COMPILE, every later one uses E_COMPILE.
The frame also carries error.details, one entry per diagnostic with its own code, file, and position, errors first, in the shape the result envelope describes under Compile diagnostics. The list is capped at 20 entries, and truncated: true is set when either the output or the list was cut.
Ready follows the contract
Theready frame reads ready.json before it fires. A compile can succeed while the browser refuses the extension, and the contract stays in error when that happens.
While the session goes on, the stream then emits a ready-failed frame, or load-refused when the browser refused the extension. Neither one ends the session, and a later compile that clears the error writes ready again. A contract error becomes a failed frame only when the process exits while ready.json still reports it.
error.code is the code that the launcher stamped, or else the code for the contract’s state. For example, browser_launch_failed gives E_BROWSER_LAUNCH, and a refused load gives E_EXTENSION_LOAD_REFUSED. E_READY_ERROR_STATUS is left for a state with no code of its own. value.readyCode names the contract’s own error id.
A browser that never started sends this frame with value.readyCode set to browser_launch_failed. A Firefox whose debugger never answers counts as a launch failure. A browser that exited sends a browser-exited frame instead, see below.
A bad --chromium-binary or --gecko-binary pin also reports readyCode: "browser_launch_failed", but its frame has status: "usage" and error.code: "E_BROWSER_BINARY_INVALID", the code every command gives that pin.
A Chromium dev session whose CDP wire failed after the browser came up still sends ready, because the browser is up. That frame carries the fault on warnings as W_CDP_...: message, the same pair the contract stamps as cdpFaultCode and cdpFaultMessage, see ready.json. Reload and HMR cannot attach until the fault is fixed.
Browser exits
A background watcher pollsready.json once per second for the launcher’s exit stamp. When browserExitedAt appears, the stream emits one browser-exited frame.
The frame’s code depends on the evidence in the contract:
E_PROFILE_LOCKEDwhen the contract shows a locked profile. The browser never started, another session holds the profile.E_BROWSER_LAUNCHfor every other unexpected exit.
value carries exitCode, exitSignal, and browserExitedAt when the contract has them. A crash has no exit code, only a signal such as SIGTRAP.
From the release after 4.1.41, the hint of a browser-exited or ready-failed frame starts with the remedy that the CLI knows for the code. Then it says that the session keeps running. For E_PROFILE_LOCKED, the remedy is to close the browser that has the profile open, or to pass --profile <path>.
Restarts and shutdown
From the release after 4.1.41, a restart whose next bundle cannot be built sends onerestart-failed frame, and the old server keeps serving. If the next server cannot start after the old one stopped, the stream sends failed and the process exits 1.
From the release after 4.1.41, a successful dev restart writes ready again once the first compile of the new server is green. That frame’s value carries restarted: true. Until then, the stream writes the compile frames as usual.
A shutdown has 10 seconds to finish, then the process exits 1. A second Ctrl+C more than one second after the first one also forces exit 1 at once. A forced shutdown never reports success.
From the release after 4.1.41, a stop that passes this bound ends the stream on failed with E_SHUTDOWN_TIMEOUT when no terminal frame came before it. A stop from an auto-exit deadline is one example. The frame’s value carries exitCode and shutdownTimeoutMs. A stop from a signal keeps its stopped frame.
From the release after 4.2.0, preview and start end their stream the same way. On SIGINT or SIGTERM, the last frame is stopped with E_INTERRUPTED, value.signal, and value.browsers, the browsers that the run was for. The run then exits 0.
From the release after 4.2.0, a signal that lands before the command has written any frame still ends the stream with one stopped frame that carries E_INTERRUPTED and value.signal. The run exits 130 for SIGINT and 143 for SIGTERM.
A session that exits with a code other than 0 also ends on a terminal frame. With an error in ready.json, the frame carries that error’s code. Otherwise it is failed with E_INTERNAL and value.exitCode.
Next steps
- Read the contract behind the frames in ready.json.
- Drive the whole loop from an agent with Driving the CLI.

