dev, start, preview, and build run writes dist/extension-js/<browser>/ready.json atomically on each compile. The current contract is schemaVersion: 2.
From the release after 4.2.0, a Safari build writes status: "ready" only after the app is packaged. A packaging failure marks the contract error with code: "build_failed".
A preview with no build loads the source folder and still writes its contract to the project’s dist/extension-js/<browser>/ready.json, with every browser field a built preview carries.
Statuses
Two-phase readiness
status: "ready" means compiled. The browser may still be launching, except under dev as described next, and the service worker may not be connected yet.
From the release after 4.1.41, under dev with a browser to launch, status stays starting after the compile and turns ready once the launcher has stamped browserPid, binary, profilePath and the debugger port (cdpPort on Chromium, rdpPort on Firefox). executorAttachedAt can follow ready unless the session was started with --allow-control or --allow-eval, where ready waits for it up to 10 seconds.
The ready line on stdout is a stricter claim in a Chromium dev session: the launcher prints it only once the runtime inside the extension has connected (executorAttachedAt). When the browser is up and nothing connects within 15 s, the launcher prints what it is waiting on instead, stamps browserUpNotAttachedAt with a hint, and prints ready the moment the attach lands.
Act tooling (eval, storage, reload, open, inspect) needs the second phase. Wait until the contract carries runtime: "attached" and an executorAttachedAt timestamp before you drive the extension.
The attach stamp is idempotent and survives recompiles. An attach also clears any earlier extension_load_refused state, because the executor runs inside the guest.
Sessions that take act verbs hold ready
From the release after 4.1.39, a session that takes act verbs keepsstatus: "starting" until the extension’s background connects or 10 seconds pass. This applies to:
previewandstartwith--allow-controlor--allow-eval. A build with no background does not wait, because nothing connects from it.devwith--allow-controlor--allow-evaland a browser that the session launches.
dev waits, the contract carries awaitingExecutorSince. The field goes away when the background connects or the wait runs out.
The wait is bounded, so ready still arrives for an extension that never connects, with no executorAttachedAt beside it. executorAttachedAt stays the field that says an act verb can run.
On Firefox, a dev session that waits needs both the RDP port and the background before it reports ready.
Field reference (schema v2)
Fields that are always present:
Fields that appear when known:
Dev additions
From the release after 4.1.39, adev contract lists what the session has that a production build of the same source lacks. Each devAdditions entry carries a kind, a value, and a reason:
The first four kinds are the difference between your manifest and the dev manifest. From the release after 4.1.41,
manifest_change reports the other dev-only changes. These are a looser pages policy, a reopened externally_connectable list, an added background, and a background kept alive. Each recompile replaces them. The launcher writes the browser_flag and browser_preference entries, and a recompile keeps them. From the release after 4.2.0, a Chromium dev session also reports content_scripts.js dev stubs as a manifest_change when the dev manifest names stubs in place of your content scripts.
A browser_flag entry says whether this launch passes the flag (applied) and what decided that (cause). cause is default, browser-flags, debugger-permission, or exclude-browser-flags. change names the one edit that flips the verdict.
A browser_preference entry appears on Chromium when the profile outlives the session, as with --profile <path>. The session sets session.restore_on_startup to 5, so Chrome opens a new tab and does not restore the pages of the previous run. The value stays in that profile after the session ends. Its cause is default, preferences when your config sets the preference, or unavailable when the browser refused the write. See Browser preferences.
Dev only and Dev flag lines. See Reading CLI output. Two flags follow the debugger permission. See Browser flags.
Error states
Thecode field names the failure class. Four codes matter for automation:
From 4.2.0, a
build that is refused before it compiles, such as by an invalid perfBudgets value, marks the existing ready.json with status: "error" and code: "build_failed". The refusal’s own code goes in endedAsFailedCode. A project that never built gets no file, and the file of a live dev session is left alone.
A load refusal outlives the next successful compile. Only a new run (starting) or a real executor attach clears it. From the release after 4.1.41, a stopped contract keeps extensionLoadRefusedAt, extensionLoadRefusedReason, and the cause.
A dev session whose browser exited before the extension loaded stays in error across recompiles, because a recompile does not bring the browser back. A launch failure outlives recompiles too, until a browser does start or a new run begins.
From the release after 4.2.0, every field that the launcher stamps is kept across recompiles of the same run. A browser verdict (browser_exited, browser_launch_failed, profile_locked, or extension_load_refused) keeps status: "error", its code, and its message after a compile that succeeds. Only compile_error and compile_failed clear on the next good compile.
Waiting with —wait
extension dev --wait and extension start --wait poll the contract every 250 ms and exit when it reports ready. Pair them with --output json for a machine result.
The wait loop refuses to trust stale files. Three checks run on every read:
- The
commandfield must match the waiting command. - The
pidmust be alive. Fordev, a dead producer always means stale, so polling continues. - For
start, a dead pid is accepted only when the contract is fresh. Freshness meansts,compiledAt, orstartedAtis within the last 60 seconds.
E_READY_TIMEOUT. A contract in error status fails the wait with its message, and the error.code of the result resolves the contract’s own code:
From 4.2.0, a contract that carries
endedAsFailedCode fails the wait with that code first.
A browser_launch_failed contract that carries browserLaunchFailedCode: "E_BROWSER_BINARY_INVALID" or "E_FLAG_NOT_SUPPORTED_HERE" fails the wait with that code and status: "usage" instead of E_BROWSER_LAUNCH.
From the release after 4.1.41, a --wait on a run that ended on a refusal answers E_EXTENSION_LOAD_REFUSED at once and does not wait for E_READY_TIMEOUT, unless the manifest changed after the refusal.
Joining the session files
The same directory holdsevents.ndjson (compile timeline) and logs.ndjson (extension console output). Every row in both carries the runId from ready.json.
events.ndjson is truncated at every run start, so it only ever describes the current run. Event types are compile_start, compile_success, compile_error, browser_exited, browser_launch_failed, and shutdown. From the release after 4.2.0, a restart_failed row records a dev restart that could not be made, such as a config or entry change whose next compiler or server failed. It carries the error code, the reason, and serving: true when the build from before the restart still serves the session and retries on the next change, false when no server is left and the session ends. A browser_exited row mirrors the launcher’s exit stamp, with exitCode, exitSignal, and browserExitedAt, so the timeline says when and how the browser went. After it, every act verb answers E_CONTROL_UNAVAILABLE naming the exit and the restart, since no service worker reconnects until a new dev session relaunches the browser. A browser_launch_failed row mirrors the launch failure stamp, with browserLaunchFailedAt and reason.
From the release after 4.2.0, a warning row records something the session warned about between two compiles, such as a reload that the extension never confirmed. It carries the warning code and the reason, and it is written in text mode as well.
Example
Next steps
- Read command results with the Result envelope.
- Stream the same session as frames with the Lifecycle stream.
- Wire the whole loop into tests with Playwright E2E.

