ready.json session contract

Poll one JSON file to know when a session is ready, broken, or gone. Every dev, start, preview, and build run writes dist/extension-js/<browser>/ready.json atomically on each compile. The current contract is schemaVersion: 2. 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

Status	Meaning
`starting`	The run began. The file resets, and `events.ndjson` is truncated for the run.
`ready`	The latest compile succeeded and the output is on disk.
`error`	The compile failed, the browser never started or exited before the extension loaded, or the browser refused or lost the extension.
`stopped`	The watch closed. Stamped with `code: "shutdown"` so a dead session can never advertise `ready`.

Two-phase readiness

status: "ready" means compiled, nothing more. The browser may still be launching, and the service worker may not be connected yet. 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 keeps status: "starting" until the extension’s background connects or 10 seconds pass. This applies to:

preview and start with --allow-control or --allow-eval. A build with no background does not wait, because nothing connects from it.
dev with --allow-control or --allow-eval and a browser that the session launches.

While 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:

Field	Type	Meaning
`schemaVersion`	`2`	The ready contract’s own version.
`schema`	`1`	Advertises that this engine speaks the schema-1 result envelope.
`status`	string	`starting`, `ready`, `error`, or `stopped`.
`command`	string	`dev`, `start`, `preview`, or `build`.
`browser`	string	The browser target that this session serves.
`runId`	string	The session identity. Join key across `ready.json`, `events.ndjson`, and `logs.ndjson`.
`startedAt`	ISO string	When the run began.
`distPath`	string	Absolute path to the compiled extension.
`manifestPath`	string	Absolute path to the source manifest.
`port`	number or null	The port that the dev server actually bound.
`pid`	number	The dev server process id. Check liveness before trusting the contract.
`ts`	ISO string	When this document was last written.
`compiledAt`	string or null	When the latest successful compile finished.
`errors`	string[]	ANSI-stripped compile errors, capped at 10 entries.
`toolchainVersion`	string	The Extension.js version that produced this tree.

Fields that appear when known:

Field	Type	Meaning
`host`	string	The dev server host.
`code`	string	Machine name for the error state, see below.
`message`	string	Human sentence beside `code`.
`instanceId`	string	The dev instance identity for multi-instance setups.
`instanceExplicit`	boolean	Whether the instance id was user-supplied.
`controlPort`	number or null	The control bridge WebSocket port.
`controlPath`	string	The control bridge WebSocket path (`/extjs-control`).
`logsPath`	string	Relative path to `logs.ndjson`.
`cdpPort`	number	Chromium launches: the CDP port, stamped post-launch.
`rdpPort`	number	Gecko launches: the RDP debugger-server port, stamped post-launch.
`webdriverPort`	number	Safari `dev` sessions: the port of the safaridriver session the launcher holds beside the app. Safari grants one automation session at a time, so attach to this one instead of opening your own.
`webdriverSessionId`	string	The session id beside `webdriverPort`.
`webdriverUnavailableReason`	string	Why the launcher holds no WebDriver session, such as Safari’s Allow Remote Automation being off, or another Safari being open when the session was asked for.
`webdriverRequestPath`	string	Safari `dev` sessions: a file a client touches to ask the launcher for a fresh WebDriver session.
`safari`	object	Safari `dev` sessions: how far the enable step got and why it stopped, so nobody parses the session log. `bundleId`, `extensionId` and `team` name the appex Safari files, `switchId` the row in Safari Settings, `enableAttempted` whether `--enable-extension` ran, `step` the last step reached (`not-asked`, `accessibility`, `safari`, `unsigned`, `pluginkit`, `enabled`, `websites`, `done`), `enabled`, `listed` and `otherWebsites` what the switches read, `reason` the sentence the step stopped on, and `earlierExtensionIds` the ids macOS still lists from earlier builds of this project, whose switches do not carry over.
`cdpFaultCode`	string	Chromium `dev` sessions: stamped when the CDP wire failed after the browser came up, with one of the debug protocol codes such as `E_CDP_TIMEOUT` or `E_CDP_NOT_CONNECTED`. The session stays `ready` because the browser is up, but reload and HMR cannot attach until the fault is fixed. Preserved across recompiles of the same run.
`cdpFaultMessage`	string	The plain line beside `cdpFaultCode`. The `ready` frame under `--output json` carries the same fault on `warnings` as `E_CDP_...: message`.
`browserUpNotAttachedAt`	ISO string	Chromium `dev` sessions: stamped when the browser process is up and the extension compiled, but the runtime inside the extension has not connected to the control bridge within the launcher’s grace period (15 s). The status stays `ready`, and the `ready` line on stdout is held back until the attach. Cleared by the first attach.
`browserUpNotAttachedWaitMs`	number	How long the launcher waited before stamping `browserUpNotAttachedAt`.
`browserUpNotAttachedHint`	string	The plain sentences beside it: the browser and its pid, the profile path, whether that profile had been run before, and the fresh-profile way out.
`profileReused`	boolean	Chromium launches: whether a browser had already run with the profile directory before this launch. A reused profile is the usual reason a browser comes up with nothing attached.
`profilePath`	string	The resolved profile directory. Ephemeral profile names are generated, so read them here.
`binary`	string	Absolute path to the browser binary this session actually launched. Stamped for every run, including the ones that did not name a binary: those are the runs where the resolver chose for you and the path is not otherwise visible.
`binaryProvenance`	string	How that binary was chosen: `managed` (the Extension.js cache), `pinned` (a binary flag or a binary variable), `system` (an installed browser), or `snapshot` (a cached dev-channel build).
`binaryPinnedBy`	string	From the release after 4.1.39, the flag or variable that named a `pinned` binary, such as `--chromium-binary` or `FIREFOX_BINARY`. Absent for every other provenance.
`browserPid`	number	The browser process id. The supported handle for tearing the browser down.
`extensionId`	string	The id that the browser serves the dist under. Browser-confirmed when available, derived otherwise.
`extensionBaseUrl`	string	Firefox launches, from the release after 4.1.39: the `moz-extension://<uuid>/` address that the browser serves the extension from. Firefox chooses the UUID per profile, so the add-on id does not reveal it.
`devAdditions`	array	`dev` sessions, from the release after 4.1.39: what the session has that the production build lacks. See Dev additions.
`extensionName`	string	The extension’s name, as build provenance.
`extensionVersion`	string	The extension’s version, as build provenance.
`browserExitedAt`	ISO string	Stamped when the browser exits mid-session without being asked. Preserved across recompiles.
`browserExitCode`	number or null	The exit code beside `browserExitedAt`.
`browserExitSignal`	string or null	The signal beside `browserExitedAt` when the browser died of one, such as `SIGTRAP` for a crash. A crash carries no exit code, so this is the one clue about why it went.
`browserLaunchFailedAt`	ISO string	Stamped when no browser process came up at all. Preserved across recompiles.
`browserLaunchFailedReason`	string	The reason beside `browserLaunchFailedAt` as one plain line, such as the spawn error with the binary path.
`runtime`	`"attached"` or `"detached"`	`attached` once the service worker has connected and can be driven. From 4.1.20, `detached` once the last connected extension context disconnects, and `attached` again on reconnect.
`executorAttachedAt`	ISO string	When the service worker first connected. Kept as provenance after a detach.
`executorDetachedAt`	ISO string	From 4.1.20, when the last connected extension context disconnected.
`awaitingExecutorSince`	ISO string	`dev` sessions, from the release after 4.1.39: when the session began to hold `ready` for the background. Removed once the background connects or 10 seconds pass.
`managedExtensions`	array	Every extension that the engine loads besides yours, as `{path, id?}` records. Subtract them by id in a census.

Dev additions

From the release after 4.1.39, a dev 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:

`kind`	`value`	Extra fields
`permission`	A permission that the dev manifest adds, such as `scripting`.	none
`host_permission`	A host pattern that the dev manifest adds.	none
`web_accessible_resource`	A resource that the dev manifest exposes, such as `hot/*`.	`matches`, the origins that can read it. Absent on Manifest V2.
`browser_flag`	A launch flag that changes what you see in the browser.	`applied`, `cause`, and `change`.
`browser_preference`	A browser preference that the session writes to a kept profile, as `name=value`.	`applied`, `cause`, and `change`.

The first three kinds are the difference between your manifest and the dev manifest. Each recompile replaces them. The launcher writes the browser_flag and browser_preference entries, and a recompile keeps them. 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.

{
  "devAdditions": [
    {
      "kind": "permission",
      "value": "scripting",
      "reason": "the dev reload registers content scripts and injects the rebuilt files into open tabs"
    },
    {
      "kind": "web_accessible_resource",
      "value": "hot/*",
      "matches": ["https://example.com/*"],
      "reason": "a content script fetches its hot update chunks from the page"
    },
    {
      "kind": "browser_flag",
      "value": "--silent-debugger-extension-api",
      "applied": false,
      "cause": "debugger-permission",
      "reason": "the manifest declares \"debugger\", so the debugging bar and its Cancel button show as they do for a user",
      "change": "list the flag under browserFlags in extension.config.js to hide the bar"
    }
  ]
}

The identity card prints the same entries as Dev only and Dev flag lines. See Reading CLI output. Two flags follow the debugger permission. See Browser flags.

Error states

The code field names the failure class. Four codes matter for automation:

`code`	What happened
`extension_load_refused`	The session runs, but the browser threw the extension out. Every other surface looks healthy, only the contract says so. Carries `extensionLoadRefusedAt` and `extensionLoadRefusedReason`.
`profile_locked`	Another live session holds the profile, so the browser never started. Carries `profileLockedAt` and a `profileLockOwner` with `host` and `pid`.
`browser_exited`	The browser process died. `start` and `preview` flip to `error`. `dev` flips to `error` only when the browser exits before the extension loaded. After that point `dev` keeps its compile status and only stamps `browserExitedAt`. A Firefox that exits before its debugger answers lands here within about a second.
`browser_launch_failed`	No browser process came up: the binary is missing, cannot be executed, or the pin is wrong. A Firefox that runs but whose debugger never answers lands here too, and Extension.js stops that process. `dev`, `start`, and `preview` all flip to `error`. Carries `browserLaunchFailedAt` and `browserLaunchFailedReason`. A launch refused for a bad `--chromium-binary` or `--gecko-binary` pin also carries `browserLaunchFailedCode: "E_BROWSER_BINARY_INVALID"`. A Gecko launch refused in system profile mode carries `browserLaunchFailedCode: "E_FLAG_NOT_SUPPORTED_HERE"`.

A load refusal outlives the next successful compile. Only a new run (starting) or a real executor attach clears it. 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.

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 command field must match the waiting command.
The pid must be alive. For dev, a dead producer always means stale, so polling continues.
For start, a dead pid is accepted only when the contract is fresh. Freshness means ts, compiledAt, or startedAt is within the last 60 seconds.

A timeout exits with 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:

Contract `code`	`--wait` error code
`compile_error`	`E_COMPILE`
`compile_failed`	`E_COMPILE_FATAL`
`dev_server_start_failed`	`E_DEV_SERVER_START`
`browser_launch_failed`	`E_BROWSER_LAUNCH`
`browser_exited`	`E_BROWSER_EXITED`
`profile_locked`	`E_PROFILE_LOCKED`
`extension_load_refused`	`E_EXTENSION_LOAD_REFUSED`
A code outside this list	`E_READY_ERROR_STATUS`

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.

Joining the session files

The same directory holds events.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. 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.

Example

{
  "schemaVersion": 2,
  "schema": 1,
  "status": "ready",
  "command": "dev",
  "browser": "chromium",
  "runId": "mdyq3k2p-a1b2c3d4",
  "startedAt": "2026-08-03T14:05:12.000Z",
  "distPath": "/home/dev/my-extension/dist/chromium",
  "manifestPath": "/home/dev/my-extension/manifest.json",
  "port": 8080,
  "host": "127.0.0.1",
  "pid": 51234,
  "ts": "2026-08-03T14:05:19.412Z",
  "compiledAt": "2026-08-03T14:05:19.401Z",
  "errors": [],
  "instanceId": "i-4b9a77",
  "controlPort": 8081,
  "controlPath": "/extjs-control",
  "logsPath": "dist/extension-js/chromium/logs.ndjson",
  "cdpPort": 9222,
  "profilePath": "/tmp/extension-js/profiles/brisk-amber-fox",
  "browserPid": 51302,
  "extensionId": "abcdefghijklmnopabcdefghijklmnop",
  "toolchainVersion": "4.0.22",
  "runtime": "attached",
  "executorAttachedAt": "2026-08-03T14:05:21.007Z"
}

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.

Introduction

Browser extension fundamentals

Getting started

Templates

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community