@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/cli/README.md

@@ -0,0 +1,895 @@
+# @product-lab/cli
+
+The `product-lab` command.
+
+The generated minimal starter reference includes its PAPI 3 transaction creator bridge, pinned signer dependencies and the standalone SDK wrapper override. Its relative app imports are checked by `tests/kit-reference.test.ts`.
+
+For the default native host, fetching a patch subset covered by the host lock selects
+the complete locked patch set. A cache miss names the build command for that full set.
+
+```sh
+product-lab [dev] [--config lab.config.ts] [--environment configured-id] [--port 5202] [--scenario scenario-id]
+product-lab check [--config lab.config.ts] [--environment configured-id] [--json]
+product-lab [dev] [--browser | --headless] [--video <dir>] [--synthetic-media] [--cursor] [--cursor-speed <speed>] [--plain]
+product-lab test [feature...] [--config lab.config.ts] [--cucumber <file>] [--tags <expr>] [--name <regex>]
+                 [--environment <id>] [--report-dir <dir>] [--dry-run] [--negative-control]
+                 [--rebuild-fixtures] [--rerun-failures <n>] [--race <runs> [--race-max-ms <ms>] [--race-seed <seed>]] [--video] [--update-baselines] [--root-calls] [--devices <names|lab>] [--own-lab]
+product-lab test --mutate [feature...] [--tags <expr>] [--name <regex>] [--max <n>] [--plan] [--report-dir <dir>]
+product-lab test --mode <name> [--base <ref>] [--changed <path>…] [--row <id>…] [--plan] [--report-dir <dir>] [--rebuild-fixtures] [--video]
+product-lab test --suite pr|merge|nightly [--base <ref>] [--changed <path>…] [--row <id>…] [--plan] [--report-dir <dir>] [--rebuild-fixtures] [--video]
+product-lab config [<group or key>] [--config lab.config.ts] [--json]
+product-lab lint [--config lab.config.ts] [--environment <id>] [--strict] [--cucumber <file>] [--json]
+product-lab coverage [--config lab.config.ts] [--cucumber <file>] [--controls] [--json]
+product-lab what-if <feature> [--scenario <name>]... [--probe "<assertion>"]... [--environment <id>] [--report-dir <dir>] [--json]
+product-lab explore [--seed <n>] [--samples <n>] [--steps <n>] [--actors <n>] [--budget <s>] [--environment <id>] [--fixture <name>] [--save <dir>] [--report-dir <dir>] [--json]
+product-lab versions [update|pin|verify]
+product-lab versions propose --from <suite-dir> --row <candidate-row> --control <control-row> [--write | --dry-run] [--body <file>] [--json]
+product-lab env show [environment-id] [topology flags]
+product-lab breakpoints [list] [<feature>] [--scenario <name>] | set <feature> --scenario <name> --step <n> | clear <feature> --scenario <name> [--step <n>] [--json]
+product-lab fixture run <name> [feature...] [--no-sources] | save <name> [--fresh] | list | delete <name> [--config lab.config.ts] [--resave] [--json <file>]
+product-lab fixture export <name> [--out <file>] [--part-size 1.9G] [--level 3] | inspect <index> | import <index> [--config lab.config.ts] [--json <file>]
+product-lab host verify --host <id> --config <targets.ts>
+product-lab host fetch|build [--host <kind>] [--config <tools.ts>] [adapter flags]
+product-lab host rebase-check --to <ref> [--host <kind>] [--config <tools.ts>] [adapter flags] [--json]
+product-lab init [--dir <path>] [--dev-server "<cmd>"] [--port <n>] [--ai] [--force]
+product-lab ai init|doctor|sync
+product-lab mcp [--config lab.config.ts] [--allow-public] [--runs-dir <dir>] [--cucumber <file>]
+                [--host-targets <module>] [--max-output-chars 20000] [--unprotected]
+# inside this repository
+bun run product-lab -- --config path/to/lab.config.ts
+bun run product-lab -- check --config path/to/lab.config.ts
+```
+
+- `dev` (default): takes the `LabRuntime` that `src/main.ts` builds for the consumer's
+  `lab.config.ts` (`createLabRuntime`, `@product-lab/composition`), starts the selected environment through it
+  (`StartEnvironment`) and serves the panel with `@product-lab/shell` over the
+  same runtime. SIGINT, SIGTERM and SIGHUP (also while the environment starts) close the
+  server, the sessions, the services and the environment (`src/stop-signals.ts`). SIGHUP is the terminal going away
+  (its window closed): it stops the lab like Ctrl-C, and the gone terminal's read and write errors are ignored from
+  then on so they never end the stop half way (backlog 191; `tests/stop-signals.test.ts`, and `tests/visible.test.ts`:
+  after SIGHUP or SIGTERM the environment is closed and no process the lab started is left). Closing tries every part (window, panel server, runtime)
+  even when one fails; a failed stop is a `LabStopError` (`src/commands/dev.ts`) that keeps the failure that ended
+  the lab first. An interrupted command otherwise exits 0 quietly, but a failed stop is printed and exits 1: what
+  the lab started may still run (`tests/dev-stop.test.ts`).
+- **One lab per configuration** (B1 step a): a second `bun run lab` (`dev`) of a lab whose window another process
+  already serves (`LabRuntime.runningLab()`, the record that window keeps in `.product-lab/running/<config name>`; one
+  per configuration, so another configuration in the folder starts and prints "Another lab (<name>, <window>) is also
+  running from this folder", `LabRuntime.otherLabsInFolder()`, `tests/running-record.test.ts`) starts nothing. With the
+  terminal app (B1 step e) it drives that window's lab instead (`src/main.ts` gives it a runtime that follows the record, read only after the flags are checked; `CliApp.besideWindow`):
+  Home, chains, people and runs are the window's (read again every half second), a run starts there, `k` says the keep
+  switch is the window's, and `q` leaves while the window keeps running (`tests/tui-attached.test.ts`); the window closing ends it, saying so:
+  "THE LAB WINDOW CLOSED", the lab it followed has ended, never "did not start" (`LabWindowClosed`, backlog 236,
+  `tests/tui.test.ts`). With plain lines it exits 1, in MCP `env_start`'s words (`besideRunningLab`): the window's address, its process, and to use that window
+  or stop it first (`tests/dev-running-lab.test.ts`). `--own-lab` (B1) keeps no record and is never refused for
+  one; with `--record <dir>` it keeps its record there instead (MCP's headless lab beside the window,
+  [the MCP README's Tools](../mcp/README.md#tools)). `product-lab mcp` gets the CLI's own command
+  (`labCommand`) to start those.
+- **Later starts** (`followLaterStarts` in `src/commands/dev.ts`): after the first start, `dev` keeps listening, and
+  every later start of the running lab, a switch from the lab window, gets a checklist of its own like the first
+  start's: headed by the operation (`Switching to …`), from the new environment's first phase until
+  `Now running <environment>` or `Could not start <environment>: <error>`.
+- **Start progress** (`src/start-progress.ts`, `StartProgressView`): while the environment starts, `dev` prints the
+  one-line stages an environment reports (`EnvironmentStartContext.progress`) and renders the phases it reports
+  through the progress port (`StartPhaseUpdate`, RuntimeEvent `environment-phase`) as a checklist. On a terminal
+  (`progressMode`: stdout is a TTY, `CI` unset, `TERM` not `dumb`) the list is redrawn in place: a spinner on each
+  active phase, ✓ for done or cached, ✗ for failed, the elapsed time, and a bar with a percentage only for a byte
+  count whose total is known; other output written meanwhile appears above the list, rows are cut to the terminal's
+  width, and `NO_COLOR` turns colours off. Anywhere else it prints one line per change of state, count, detail or
+  tenth of a known size (while a phase stays active, at most one such line per 5 s; its last line always prints), plus
+  a `(still running)` line for an active phase quiet for 60 s. A phase is shown done only
+  when its environment reported it done: a stopped or failed start marks what was active as failed and leaves
+  waiting phases waiting. When an environment reported phases, the lab window (or panel) is the last one. An
+  environment that reports none prints only its one-line stages.
+- **Agents beside the lab** (`src/agents.ts`, `src/tui/agents-menu.ts`; _artifacts/design/one-lab-three-ways.md,
+  point 4): on Home, `a` lists Claude Code and Codex, each found on the PATH or greyed with the line that installs it,
+  and opens the one chosen in the lab's folder, where the generated MCP config (`.mcp.json`, the Codex config) attaches
+  it to the running lab. Where it opens (`besidePlan`, pure over the variables): a tmux split inside tmux (`TMUX`); else
+  a new tab or window of the same terminal app (`TERM_PROGRAM`: Apple Terminal and iTerm through `osascript`, WezTerm
+  through `wezterm cli spawn`, Ghostty; kitty by `KITTY_WINDOW_ID` through `kitty @ launch`); else here: the app pauses
+  (Ink's `suspendTerminal`: it leaves the alternate screen and raw mode), the agent runs on this terminal in the
+  terminal's foreground group (the `TerminalCommandRunner` port) with Ctrl-C its own (`holdInterrupts` in
+  `src/stop-signals.ts`), and the lab keeps running; when the agent exits the app draws again. A terminal app that
+  refuses to open one (`osascript` without the Automation permission) falls back to here. The window's Tools page gets
+  the same list (`agentsService`, `DevOptions.agents`, served as `ServeOptions.agents`). Tests: `tests/agents.test.ts`
+  (the PATH lookup, each plan, AppleScript quoting, the launcher over fake runners), `tests/tui.test.ts` (the menu,
+  greyed rows, `esc`), and `tests/tui-start-harness.ts` with `HARNESS_AGENTS=1` for a pty proof with a real agent
+  binary.
+- **Terminal app** (backlog 182; `src/tui/`): in an interactive terminal, `dev` shows a full-screen app (Ink, React
+  for the terminal) instead of plain lines. It takes the terminal from the first moment, as Claude Code and Codex do
+  (lane "start in the app"): the CLI opens it (`openTerminalApp` in `src/tui/start.ts`) before the lab is read, so
+  nothing is printed under the shell's history; the start's checklist shows in its Starting screen
+  (`src/tui/starting.ts`, from the same `StartProgressView` phases and stages), with only `l` (the lab's lines) and `q`
+  (stops the start after asking). A kept chain whose day ended asks there whether to replace it (`DevOptions.ask` is
+  the session's `ask`: its lines, `y` replaces it, `n`, Enter or esc keeps it and the start fails with the
+  `--clean` words; plain lines in a terminal ask with readline). A start that fails (the chain-clock refusal, a port in use) shows inside with its
+  words until `q`; then the app leaves the alternate screen and the failure is printed once under the shell's history
+  (`insideTerminalApp` and `ShownFailure` in `src/commands/dev.ts`). Proof in a pty: `tests/tui-start-harness.ts`. Home shows the chains (best and final block, a chain with
+  no new block for a minute), the people (host, state) and the latest run step by step: each step's screen and chain
+  checks (where and at which block the chain was read), its time, why it failed and what the lab found it sent, and
+  what the run wrote. Keys open screens: `c` chains (which runs, the saved states with where each came from and where
+  it is stored; `s` switches, `x` resets, both ask first; "Keep chain and people between starts" in the window's words, `k`
+  turns it), `p` people (where each came from and when, whether they are
+  kept between starts as the window's switch says it, from `keepBetweenStarts`, and where; `n` makes one on a host you pick, hosts the lab does not declare greyed with the config line that turns them
+  on; `d` removes one after asking), `s` scenarios (every one with who it needs and where it runs, a live-network-only
+  one greyed with the command that runs it; `/` filters, `⏎` shows its steps, `r` runs it as the window's Run does,
+  asking first before a switch or the session's root calls; with the lab's own window open it goes through the
+  window's runner, so each person acts in their tile, `throughWindow` in `src/tui/start.ts`), `r` the run (`←` `→` through the session's runs), `h`
+  history (this session's runs and where recordings are kept), `g` config (what the lab's config turns on, the rest
+  greyed with the lines that turn it on, docs/feature-map.md; "Chain pace": fast or real time, with how long the chain's day
+  has left; the Chains screen says the same), `l` logs (the lab's own lines, then each log file the
+  environment reports, as MCP `tail_logs` finds them; `/` filters), `o` brings the lab window forward, `a` opens an
+  agent beside the lab (below), `?` help, `q`
+  stops the lab after asking (Ctrl-C at once), `esc` back to Home. It reads `LabRuntime.snapshot()` on every runtime
+  event and once a second, as the lab window reads it: no second source of truth; the words for people, writes and
+  where a scenario runs are the window's own (`@product-lab/shell/words`). What the lab prints while the app shows
+  goes to Logs, and is printed when the app closes so the scrollback keeps it. The app is the whole screen and never
+  more (lane E1): it draws on the alternate screen (the terminal's own lines come back when it closes, on a signal or
+  a crash too), fits the terminal's rows with the key bar at the bottom, cuts every line short of the last column and
+  never wraps, and on a resize clears the screen and draws again for the new size. The terminal's title says
+  "product-lab · <lab>" while it shows, the title before put back when it closes (lane E2). It takes the mouse while
+  it shows (lane tui-wheel, 8 October 2026; `src/tui/mouse.ts`): SGR mouse reporting (`ESC[?1000h ESC[?1006h`), so the
+  wheel scrolls the app, never the terminal's buffer behind the alternate screen (macOS Terminal showed the shell's old
+  lines above the app). A turn of the wheel is the screen's ↑ or ↓: a list's marker moves, Logs go back through their
+  lines and forward again, Home, Run, Help and the start's checklist move a line at a time (`src/tui/scroll.ts`); it
+  never answers a question. Ink drops every mouse report as a control sequence that names no key, so none is typed into
+  a screen; the wheel is read from the chunks Ink reads (`MouseCapture`). Reporting is off again when the app closes
+  (before Ink lets go of the input), at the process's exit (a crash too), and while an agent runs in this terminal.
+  Selecting text needs Option+drag in macOS Terminal (Shift+drag in most other terminals); Help says so. Pipes, `CI`, `TERM=dumb` and
+  `--plain` keep the plain lines (`terminalAppEnabled` in `src/lab-flags.ts`). Ink 8.0.0 and React 19.3.0 (the
+  panel's) are dependencies; Ink loads only when the app shows, and before the lab starts anything (`loadTerminalApp`
+  in `src/commands/dev.ts`, lane E3): a package that is not installed is said at once with `bun install`, and the lab
+  runs with plain lines instead of stopping once its chain, people and window are up. Render tests over fixed snapshots, with controls:
+  `tests/tui.test.ts` (ink-testing-library 4.0.0); the mouse in `tests/tui-wheel.test.ts` (the reports read and the
+  ones that are not the wheel, no report typed into a filter, the wheel on Logs, a list, a long Help, a question and an
+  agent run here, a crash in a child process, and the app's end, crash and SIGTERM in a pseudo-terminal through
+  `script`). `tests/tui-pty-harness.ts` runs the app over the same test doubles
+  for a real terminal (a pty), to read its screen with a terminal emulator; it is not a test of its own.
+- **One lab journey** (`src/lab-flags.ts`): `dev`, every example's `bun run lab`, opens the lab in a
+  Playwright-controlled Chromium window (`@product-lab/shell/visible`) by default. There Run is **Watch** (drives
+  the real app inside its iframe, highlighted) or **Background** (headless through the actor sessions, as CI);
+  any other tab on the lab's URL runs in the background and says so. Closing the window stops the lab.
+  - `--browser`: open no window; the URL is for your own browser (runs there run in the background).
+  - `--headless`: run the lab window without showing it (CI, agents); Watch still drives its frames.
+  - `--video <dir>`: record the lab window.
+  - `--synthetic-media`: accepted so older commands still run, and changes nothing: since 22 October 2026 the managed Chromium window always uses a synthetic camera and microphone, so no app in it reaches the machine's own devices (a video call holding the camera cannot fail a run). Recordings label the feeds synthetic.
+  - `--cursor`: show mode; each identity gets a named cursor in its colour that glides to its target and ripples at the
+    click, never later than the highlight delay. It is on by default in the headed lab window (Settings turns it on or
+    off and keeps the choice); `--cursor` turns it on in a `--headless` one. `--cursor-speed
+    slow|normal|fast|<ms>` sets the glide (0 to 5000 ms, anything else is refused) and implies `--cursor`
+    ([Identity cursors](../panel/README.md#identity-cursors)).
+  - `--visible`: the flag from before the window was the default; accepted for one release, means the default.
+  - `--no-hot-reload` / `--hot-reload` (backlog item 5): `dev`
+    watches each app's declared source (`apps.<id>.watch`) by default, off when `CI` is set (`hotReloadEnabled`);
+    a change reloads each running identity's app between its steps, keeping the environment, host sessions and
+    wallets, and prints what it did ("Notes reloaded (build 2, 0.9 s)", a restart path's "not reloaded: … Stop and
+    Start each identity", a failed build). Since backlog item 65 it also follows each app's dev server through the
+    lab's proxy, with or without a declared `watch`: an
+    update passes in place while nothing runs ("Notes updated in place by its dev server (build 4)") and is held
+    while a step runs. With `--no-hot-reload` (and under `CI`) no update reaches a page at all. `watchApps` in
+    `src/commands/dev.ts`; `startDev` watches only with `hotReload: true`. `tests/lab-flags.test.ts`.
+  - Refused before the lab loads: an unknown flag (exit 2, with the accepted list, `DEV_FLAGS`), and `--browser`
+    with `--headless`, `--video`, `--synthetic-media`, `--cursor`, `--cursor-speed` or `--visible` (exit 1, naming both).
+  `startDev(runtime, options)` (`@product-lab/cli/dev`) is the same path for in-process tests; there the window is
+  opt-in (`visible: true`), so existing callers keep a plain panel.
+- `check`: validates `lab.config.ts` and prints, for every environment (or the
+  one named by `--environment`), which apps are available and exactly which
+  chain, service, capability or secret is missing otherwise. It starts nothing
+  and prints no secret values. `--json` prints the panel registry for one
+  environment (the default one unless `--environment` is given). The report is
+  `CheckLab`'s, the same MCP `check` returns.
+
+- `breakpoints` (`src/breakpoints-command.ts`, backlog 17, 30 September 2026):
+  lists, sets and clears the lab's step breakpoints
+  (`LabRuntime.breakpoints()`), its local state in `<lab>/.product-lab/breakpoints.json`, never the feature file. Steps
+  are numbered from 1 with Background steps first, as the panel numbers them; `set` refuses a feature, scenario or step
+  that does not exist; `list` shows a breakpoint whose step changed since it was set as stale, with why. A feature run
+  in the lab panel (Watch or Background) or an MCP `run_scenario` with `inProcess` pauses before each one; `product-lab
+  test` runs Cucumber in its own process without the pause gate, so breakpoints never stop it. Starts nothing; usage
+  errors exit 2 before the lab loads (`tests/breakpoints-command.test.ts`).
+
+- `fixture` (`src/fixture-command.ts`): scenarios that start from a saved state
+  (`defineLab({ fixtures })`). `run <name> [feature...]` starts the fixture's environment; a saved fixture whose key
+  is the one computed now is restored before the environment's identities first start (`LabRuntime.startFromFixture`,
+  since 30 September 2026: the start opens the sessions for the restore, then restores; `environmentStartMs` covers
+  both and `restoreMs` is the restore's own time), nothing saved runs the setup
+  feature in this process and saves the state when it passes (`SaveFixture`), and a saved fixture whose key differs is
+  refused with every reason, exit 1, nothing restored or run (`--resave` runs the setup again on the running state
+  and saves it). Then each feature runs in this process (`RunFeatures` `inProcess`) with its actors bound by name to
+  the fixture's identities. The environment stops at the end; `--json` writes the timings and results. `save`,
+  `list` (starts nothing) and `delete` manage them. A fixture saved from the running state in the lab (no setup) is
+  listed with that origin, restored by `run` when it fits and refused (never rebuilt) when stale or missing.
+  A fixture built on another (`from`, backlog 1f, 3 October 2026) restores that
+  fixture first and runs its setup on that state with its identities; the base must be saved and fit (else refused
+  with its reasons: save the base first). Restoring it restores it alone.
+  Every fixture command starts its environment keeping chain and people (backlog 183), `run` too since backlog 232
+  (8 October 2026): a fixture saved on a kept start keeps its people in the kept folder, and a run that kept nothing
+  refused its restore ("the session keeps its identities in no directory") or, on the relay-less `fast`, restored
+  nothing (a chain that is not kept saves nothing). A fixture saved before a reset of the Paseo copy is refused up front:
+  its people were kept with the old chain generation, and the words say to save it again with `--fresh`.
+  Since 30 September 2026 (backlogs 76 and 77):
+  - **A published bundle before the setup.** `run` with nothing saved first asks the lab's fixture sources
+    (`defineLab({ fixtureSources })`) for the newest published bundle that fits (same key: setup, lock, inputs,
+    runtimes; platform; not expired), downloads it while the environment starts without its first identities
+    (`startFromFixture({ importing: true })`), imports it and runs the features on it (`Imported <name> from <source>`,
+    `action: "imported"` in `--json`). When no bundle is used it prints why (`No published bundle is used:` and each
+    reason, then `The setup runs instead.`) and runs the setup as before; after a failed import the environment is
+    started again first. A bundle that was imported and then does not fit the running environment is an error, never
+    a silent setup; so is an import that failed after it began replacing the state (`FixtureImportIncompleteError`:
+    the environment may hold the bundle's identities, so the setup is not run on it; the message says to run the
+    command again or to build with `fixture save <name> --fresh`). `--no-sources` skips the sources.
+  - **A failed save can be retried.** Before a setup runs, a marker is written
+    (`<lab>/.product-lab/fixture-runs/<name>.setup-unsaved.json`, `src/fixture-setup-marker.ts`) and it is cleared when
+    the state is saved. A later `run` or `save` that finds the marker on the same state of the same environment
+    refuses before running anything: the setup already ran there and its state was never saved, so running it again
+    would run it twice on one chain. The refusal names the one command that cleans it: `fixture save <name> --fresh`,
+    which resets the environment (`LabRuntime.resetEnvironment`), runs the setup and saves. An environment that was
+    reset or started anew since (another provenance) is not refused. It starts the environment keeping its chain, as
+    every save does (a relay-less chain that is not kept saves nothing); the Paseo copy resets while it keeps (backlog
+    229). An environment with no reset at all (an attached fork, a workspace its config names) refuses `--fresh`
+    before the setup, with its own reason.
+  - **A setup never makes its people twice** (backlog 221, 8 October 2026). Before a setup runs (also with `--resave`),
+    a running state that already holds identities the saved record says its setup makes (`prepared`) is refused, by
+    name, with `fixture save <name> --fresh`; nothing runs. A base fixture's restore (`from`) and `--fresh` replace the
+    state first and are not refused. A record naming no `prepared` identities cannot tell; the save then refuses the
+    duplicate name before anything is saved (`SaveFixture`, backlog 222).
+  `tests/fixture-command.test.ts`.
+  Sharing (`src/fixture-sharing-command.ts`, 30 September 2026): `export <name>` writes the
+  saved fixture as a bundle (the index `--out`, default `./<name>.fixture.json`, and parts `<name>.fixture.tar.zst.001`,
+  … of at most `--part-size`, default 1.9G below GitHub's 2 GiB asset limit), starts nothing and prints the parts, their
+  sha256 and the test-key notice; `inspect <index>` says whether a bundle fits this checkout and machine (exit 1 with
+  every reason); `import <index>` refuses a bundle that does not fit before anything starts, otherwise starts the
+  fixture's environment, imports it (`LabRuntime.fixtureSharing().importFixture` with the session's confirmation),
+  prints the moved directories and what the environment moved, says whether the fixture now fits, and stops the
+  environment. Sources (`src/fixture-source-command.ts`, backlog 1g): `sources` lists the lab's fixture sources.
+  `pull <name> [--source <id>] [--download-only]` downloads the newest published bundle that fits into
+  `<PRODUCT_LAB_CACHE_DIR>/fixtures` while the fixture's environment starts, prints the attestation and why other
+  bundles were skipped, then imports it as `import` does (a refused download stops the environment again).
+  `push <name> [--source <id>]` exports and publishes to a directory source, or prints the `gh release upload` for
+  a release, with the notes that the release must exist and that a hand upload has no attestation; it never uploads.
+  `tests/fixture-sharing-command.test.ts`. Maintenance (`src/fixture-refresh-command.ts`, backlog 1i): `check` starts
+  nothing and exits 1 when a fixture is stale or missing (for a nightly job); since 3 October 2026 (backlog 1d) it gives
+  each fixture a cache key (`fixtureCacheKey`, `--json` `cacheKey`) for a CI cache (`tools/ci/fixture-cache.sh`). `refresh <name> [--rebuild]` leaves a
+  fixture that fits alone. It upgrades in place when the plan says so. Otherwise it rebuilds. Since 30 September
+  2026 a rebuild on an environment that offers a reset starts it as it is and resets it, so the chain and the session's
+  records begin together (setting the session directories aside on a resumed chain left records of identities the
+  directories no longer held: "Identity … changed account"). An environment without a reset, or one whose saved state
+  no longer starts, takes the older path: it sets the session directories aside, starts the environment fresh, runs the
+  setup, saves with `rebuilt` and deletes the set-aside directories; if the setup fails, it puts them back after the
+  stop. `tests/fixture-refresh-command.test.ts`. `dev`
+  (`bun run lab`) takes `--update-runtime` or `--refresh` for its first start (`LabRuntime.startEnvironment({ update })`);
+  an environment that does not list the update refuses before starting. `dev` also takes `--rpc <chain>=<url>`
+  (repeatable) and `--rpc-reason "…"` (3 October 2026): this start's RPC per chain for an environment that takes one
+  (`EnvironmentProvider.rpc`), over lab.config's and the lab window's remembered choice (`src/rpc-flags.ts`,
+  `LabRuntime.startEnvironment({ rpc })`). Refused before anything starts: a chain the environment does not take, a URL
+  with credentials (it belongs in lab.config.ts as a secret, `fromEnv`; no message names the value), and an endpoint
+  off this machine without a reason. The start line names each chain's RPC and where it came from; a secret's URL
+  shows as scheme://host or `[redacted]`. `tests/rpc-flags.test.ts` (fixture `tests/fixtures/rpc.lab.config.ts`).
+  `dev` takes `--option <id>` (backlog 184): one of the environment's options ("light"), remembered as the person's
+  choice for its next starts; without it the start runs the last choice, else the option this machine meets, and says
+  why. `check` refuses it (it starts nothing).
+- Keep chain and people between starts (backlog 183, 6 October 2026): the interactive lab (`product-lab`,
+  `product-lab dev`) keeps them unless the switch is off, in the lab window or the terminal app's Chains screen (`k`;
+  both save the lab's `keepBetweenStarts` setting; `runtimeOptions` gives the runtime its `KeepPolicy`); with `CI` set, and for every other command, a start is clean unless asked. A kept chain that went stale (its clock ran past the wall clock's day at the fast pace) is refused; in a terminal the lab asks "Replace it with a new chain? The people kept with it are discarded. [y/N]" and y starts again with `replaceKept`; otherwise it says how to go on, naming `bun run <script> --clean` when started from a package script (`npm_lifecycle_event`), else `product-lab --clean` (`src/commands/chain-day-ended.ts`, `DevOptions.ask`). `dev --keep` or `--clean`
+  chooses for one start (refused together, and for `check`); the start line says what the start did and why
+  (`keepLine`). `dev --fixture <name>` (lane speed, 7 October 2026; `DevOptions.fixture`) starts from that saved fixture:
+  `LabRuntime.startFromFixture`, its chain and people restored as the environment starts, so the running state is
+  exactly the fixture (a scenario naming it is `kept`, an `@isolated` one saves no copy). A fixture that does not fit is
+  refused with its state and reasons, `Fixture <name> is <state> here, so the lab did not start from it: …`, and the lab
+  is stopped; never a plain start in its place. Refused with `--keep`, `--clean`, `--refresh`, `--update-runtime`,
+  `--option`, `--candidate`, `--rpc` and for `check` (`tests/dev-fixture.test.ts`). `product-lab test --keep` exports `PRODUCT_LAB_KEEP=1` to the run, whose lab keeps them; fixture and
+  what-if commands always keep (`keep: true`), since they save and restore state.
+- `mcp`: serves the lab to AI agents over MCP on stdio (`@product-lab/mcp`; tools,
+  safety model and client registration in [the MCP server's README](../mcp/README.md)). stdout
+  belongs to the protocol; everything else goes to stderr.
+- `test`: runs the lab's feature files through its own Cucumber configuration and step files
+  (`RunFeatures`, `src/test-command.ts`). B1 (d): with this lab's window open (its running-lab record), `src/main.ts`
+  gives `test` a runtime that follows it (`followRunningLab`), and the run goes to the window's lab: in its process, on
+  the environment it runs, with the bundled steps, so it shows there live while its output streams here and its report
+  is written as usual (`src/test-in-window.ts`). A flag that needs a lab of its own (`--workers`, `--race`, `--suite`,
+  `--devices`, `--mutate`, `--negative-control`, `--dry-run`, `--candidate`, `--cucumber`, `--keep`,
+  `--rebuild-fixtures`, `--rerun-failures`, `--root-calls`, `--video`, `--update-baselines`), a window with no
+  environment and another `--environment` are refused saying what to do; `--own-lab` runs a lab of its own as before
+  (`tests/test-in-window.test.ts`). Feature files must be the lab's (its `features` globs,
+  else every `.feature` under its directory); without any, the Cucumber configuration's own
+  selection runs. `--negative-control` asserts the run fails at exactly one scenario step, not a
+  hook, as its tags say (tag-only controls, 6 October 2026; [the scenario skill, "Negative controls"](ai-kit/skills/product-lab-scenario/SKILL.md#negative-controls)):
+  its scenario's last step (`@fails-at-step-N`: that one), from that step's own check and never for an infrastructure
+  reason (`@fails-with:<reason>`: that reason only; a refusal before the scenario ran counts only when it is named,
+  `unsupported-here` or `scenario-refused`). The tags are the only declaration: `--expect-step`/`--expect-marker` and
+  lab.config.ts `negativeControls` are gone and refused, saying so (config redesign, step 8). Under
+  the verdict the failure it judged: `<reason>: <message>`; a failure elsewhere or for another reason prints
+  `NOT a valid negative result: failed for another reason`. With no feature path, `--negative-control` runs every
+  tagged control (`every-control.ts`: a tagged feature whole, a tagged scenario alone as `path:line`,
+  `@runs-with:keep,rebuild-fixtures` adding those flags), one run each (`--report-dir <dir>/<control>`), and prints
+  `Negative controls: N of M failed as intended` with the ones that did not; exit code 0 only when each did. A control
+  whose scenarios do not run on the run's environment by their tags (`@environment:`, `@live-network`, `@root-calls`,
+  read from the listing's `runsOn`) is listed as not for it and never started; one whose steps were all skipped once
+  running (a condition such as `@policy-1` the chain does not meet) is judged `not-run`, `control <path>: not run here:
+  <why>; inconclusive`, and exits 3 (`NOT_RUN_EXIT`). Both are listed as `not run here (not passed)`, never counted as
+  passed; the whole run passes only when at least one control ran and every one that ran failed as intended. With
+  `--dry-run` it plans each control and judges none (`N of M planned (dry run: none judged)`): nothing failed, so a
+  judgement would read "passed". `--tags` and `--name` select controls before any runs (lane speed, 7 October 2026): a
+  control none of whose scenarios the selection picks (their tags, the feature's included; their names or Examples
+  rows' names) is listed as `not selected by --tags "…"`, never run, and neither counts nor fails the run; a selection
+  that picks no control runs nothing and exits 1 (`none selected by …`). One start for the controls (lane speed, 7 October 2026; `shared-controls.ts`): a
+  control with no flags of its own (no `@runs-with:`; the command's only `--config`, `--environment`, `--tags`, `--name`,
+  `--verbose`) runs in this process on an environment the command starts once (`Starting <environment> once for the controls`), as a run
+  in the lab window does, instead of in a run that starts and stops its own. Each still starts fresh: the environment
+  restarts before the next control when one left it changed (`leftChanged`: a step ran or a fixture was restored, and
+  no `@isolated` give-back put the start state back; `The last control changed the environment: restarting it`). A
+  control none of whose scenarios fits the chain is refused before it starts, `control <path>: not run here: Not for
+  this chain: …; inconclusive`, exit 3 as before, and costs no start. A control with flags of its own runs as before,
+  after the shared environment stopped; a dry run shares nothing. A control's run carries `PRODUCT_LAB_CONTROL_RUN=1`
+  (`CONTROL_RUN_VARIABLE`: in its Cucumber process's variables, and in this process while the shared environment runs;
+  not in a dry run), so a lab may bound the checks its controls fail more tightly and say so (Notes: `checkBound`).
+  (`tests/bundled.test.ts`: planted copies with a wrong reason, a wrong
+  step and no `@fails-with` are not valid; `tests/every-control.test.ts`). Exit code 0 when the run passed (a negative control: when it
+  failed as intended), 3 for a control none of whose steps ran here, 1 otherwise; a run in which no scenario ran fails. With `--report-dir` the
+  runner's own report is `<dir>/product-lab-test.json`; the default run directory is
+  `<config dir>/.product-lab/test/<run id>`. Every run also writes `junit.xml` and a
+  self-contained `report.html` (no script, no external resource; images embedded) beside it
+  (`src/reports/`). The report reads in about one screen per scenario (backlog 187): each step's JSON and text
+  attachments are closed under a one-line summary ("call trace: 1 call (notes.publish), 4 readings, 24 KB"), its
+  screen and chain readings stay open as one verdict line each ("✓ chain, Bulletin #24 (finalized): holds exactly that
+  text"; a failed one gives what was expected and what was found), errors and images stay open, and consecutive
+  passed hooks fold into one closed line ("2 hooks passed, 2 ms"); a failed hook stays open
+  (`tests/report-attachments.test.ts`).
+  A scenario tagged `@fixture:<name>` (on it, its Rule or its feature; backlogs 1b and 1c, 30 September 2026)
+  starts from that saved fixture: it is restored
+  before the scenario, so no scenario sees another's changes (`@fixture-shared` on a feature or Rule restores once for
+  its scenarios in a row), and the output lists each scenario's restore and its time. An undeclared fixture is refused
+  before anything starts; a missing or stale one refuses its scenario with every reason unless `--rebuild-fixtures`
+  (then its setup runs and is saved first, on a state nothing changed since the environment started). Without
+  `--environment`, a run whose fixtures all belong to one environment starts that one (`tests/test-fixtures.test.ts`).
+  `--rerun-failures <n>` (backlog 26, 3 October 2026):
+  after a failed run, each failed scenario is rerun up to n times (1 to 20) from the state it started on, through its
+  run bundle (`bundle`, then `reproduce --reruns`), and reported `flaky` (a rerun did not fail) or `failing` (every
+  rerun failed); one bundle per scenario keeps every run, and a scenario that cannot be rerun is named with why. The
+  exit code is unchanged: flaky never counts as passing (`src/rerun-failures.ts`, `tests/rerun-failures.test.ts`).
+  `--race <runs>` (backlog 32, 4 October 2026): race hunting. The selection runs once per seed
+  (1 to 100 runs, one at a time, each in `<report dir>/run-<n>-<seed>`; run 1 on `--race-seed`, else a random seed,
+  later runs on seeds drawn from it). Before each step an identity takes after another identity's, and before every
+  identity's step in a run-together group, the lab waits a time drawn from the scenario's seed, up to `--race-max-ms`
+  (default 300); one actor's steps never change order. The command passes only when every run passed, prints each
+  failing seed with the command that replays it (`--race 1 --race-seed <seed>`), and writes `product-lab-race.json`;
+  each recording keeps its seeds and waits, and `reproduce` applies them again. Refused with `--workers`, `--suite`,
+  `--negative-control`, `--dry-run`, `--rerun-failures` and `--mutate` (`tests/test-race.test.ts`). Since backlog 118
+  (5 October 2026) the runs are the runtime's own race loop,
+  the Tools page's (`LabRuntime.startTool` with the command's selection and folder, `src/tool-run.ts`); its seeds, waits,
+  printed lines and `product-lab-race.json` are pinned from the command's own loop before the move
+  (`tests/test-race-compat.test.ts`).
+  A scenario tagged `@isolated` (backlog 17h, 3 October 2026) gives the state back: it is saved before the scenario
+  and restored after it, so a saved local fork is left as the scenario found it; the output says
+  `Isolated scenario: the start state was saved|kept|recovered|restored …` with the time.
+  Cancellation before or during preparation refuses to start a feature run. If a handle
+  arrives after cancellation, the command sends SIGINT once and joins both completion
+  and its cleanup before returning.
+- `test` prints a plain, readable run (backlog 186, 6 October 2026, `src/plain-output.ts`):
+  the versions line without paths; then the run's own lines, each marked by the run's process (`PLAIN_MARK`):
+  the start and end phases with their times, and each scenario as a group of steps, each with its time and its checks in
+  the lab window's words (`screen ✓ · chain ✓ Bulletin #28`). A failed step shows the lab's own message without a
+  stack. The lab's own console lines are counted and kept in `cucumber.log`; a run that failed outside its steps shows
+  their last 12. After the run come the result with its time, where it failed and the lab's answer (`explainFailure`),
+  the host check in the window's words (`@product-lab/shell/host-bypass-words`), the reports, the unchanged
+  `product-lab test <id>: …` line, a control's verdict, and last `Look at:` (the report, the scenario's recording, the
+  hosts' logs the failed run kept, backlog 192, the log). A failed step's error is said once, under the step;
+  `What the lab saw:` only when no step said it, with the reasons a refusal lists under its first line (at most three, then how many more). `--verbose` prints the run as before. With `GITHUB_ACTIONS=true` the run's process groups each phase and scenario (`::group::`)
+  and annotates a failed step on its line (`::error file=…,line=…`) (`tests/plain-output.test.ts`,
+  `tests/test-command.test.ts`). The same for every kind of run (186's leftovers, 6 October 2026):
+  - `--suite`: each row opens with `Row <id>: <n> scenario(s) on <environment>` (from `RunSuite`), then its run's own
+    lines, then the result with one line per row (`<row>: <status> (<reason>) in <time>`), the unchanged suite line
+    and `Look at:` (report, summary, the hosts' logs its failed rows kept).
+  - `--workers`: each worker's lines after `[worker <n>]`, without GitHub groups (the workers' lines interleave), an
+    annotation at the start of its line. Then the result, one line per worker (a failed step's error is not said
+    again), the unchanged workers line and `Look at:` (the record, each failed worker's run, the hosts' logs their
+    failed recordings kept).
+  - `--race`: each run's header, its own lines, its unchanged run line and its result in words. Then the race's
+    lines and `Look at:` (the race record, each failed run's report and the hosts' logs it kept).
+- `test --root-calls` (4 October 2026): confirms this run's root calls (`PRODUCT_LAB_ROOT_CALLS=1` to the Cucumber
+  support, which calls `LabRuntime.allowRootCalls` with the session's confirmation). Only an environment whose lab
+  declares `rootCalls` has any; without the flag every root call is refused before anything is signed
+  ([the domain README's `root-calls/`](../../core/domain/README.md#folders-and-exports)).
+- `test --video` (backlog 52 and the headless half of 18b, 4 October 2026):
+  sets `PRODUCT_LAB_RECORDINGS_VIDEO=on` for the run (every row of a suite). Every browser the lab's sessions launch
+  records each page as video into the recordings directory's `videos/`, one file per page through its navigations;
+  each scenario's recording lists, in `capture.videos`, the videos of the pages its steps acted in and when each page
+  opened (the recording's own clock), so a step's place in a video is `step.startedAt - openedAt`. Videos are not
+  redacted: a value typed into a field, a secret included, can be seen in them. Not with `--workers` (refused).
+- `load --action "<sentence>" (--actors <n> | --ramp <n,n,…>) [--each <k>]` (backlog 43, `src/load-command.ts`): many new
+  identities acting at once on the environment, measured from the load's recording (`LabRuntime.runLoad`): finalized
+  transactions per second, submission to inclusion and to finality (p50, p95, max; unknown times counted), failed steps
+  by error, peak concurrency, chain lag and machine load. A ramp runs one load after another and stops at the first
+  that did not complete. The machine guard stops a load starting steps (1.5 load per CPU, load 64, 2 GB free memory)
+  and says so; below 15 GB of free disk it does not start. `--max-p95-ms` and `--max-failures` make it a check.
+  Record: `product-lab-load.json`. Exit 0 when every load completed and met its thresholds (`tests/load-command.test.ts`).
+- `test --devices <names|lab>` (backlog 31c): the devices resolve first
+  (`LabRuntime.runDevices`: `"Pixel 7,Desktop"`, or `lab` for `defineLab({ devices })`; an unknown or repeated name
+  refuses the command, with the nearest names, before anything runs); then the same plain run once per device, one after
+  the other, each with `PRODUCT_LAB_DEVICE` (every identity's app emulates the device; visual baselines are the
+  device's own) and, with `--report-dir`, its own `<report dir>/<device>`. A line per device and a summary are printed;
+  the command passes only when every device passed. Not with `--suite`, `--workers`, `--mutate`, `--negative-control`, `--race`
+  or `--rerun-failures` (refused). `tests/test-devices.test.ts`.
+- `test --update-baselines` (backlog 40): sets
+  `PRODUCT_LAB_BASELINES=update` for the run, so each step's visual check (`@visual`, or the lab's `checks.visual.all`)
+  replaces its baseline beside the feature with this run's screenshot. Without it a missing baseline is written and an
+  existing one compared; CI sets `PRODUCT_LAB_BASELINES=strict`, where a missing baseline fails the step. Not with
+  `--suite`, `--workers`, `--negative-control` or `--mutate` (refused). `tests/test-baselines.test.ts`.
+- `dev` with `PRODUCT_LAB_RECORDINGS_VIDEO=on` (backlog 18b, the window half, 4 October 2026):
+  the lab window and each detached identity window record into the recordings' `videos/` (`RecordingListing.videos`),
+  and the recordings of the window's runs name them: the lab window's one video for no identity (`lab-window`), a
+  detached window's for its identity (`detached-window`). `--video <dir>` still records the lab window where it says,
+  never named; a recording then says why. Background runs keep the actors' own pages (`test --video` above).
+- `test --mutate [feature…]` (backlog 38, test the tests, 4 October 2026):
+  changes one expectation on purpose and the scenario must fail at that step (`src/mutate-command.ts`; since backlog 118
+  the mutants run in the runtime's own test-the-tests loop, the Tools page's, through `LabRuntime.startTool`). The runtime
+  plans the mutants (`LabRuntime.mutationPlan`): one per positive assertion step, its first literal value changed (a
+  string gets " (changed by product-lab)", an int 1 more); absence checks ("do not include", "at most"), earlier
+  steps' outputs, step groups, custom steps, outlines and negative controls are not changed, each with why, and a
+  scenario with nothing to change says so. Each mutant is a copy of its feature file with only that line changed, in
+  `<lab>/.product-lab/mutants/<run>/<n>/`, run as a negative control of that scenario expecting the changed step:
+  killed (it failed there), survived (it passed: the assertion never checked the value; exit 1) or inconclusive (it
+  failed elsewhere or did not run, with why). `--plan` lists the mutants and starts nothing; `--max <n>` runs the first
+  n and counts the rest as not run; `--tags`, `--name`, `--environment` and `--cucumber` select as usual; the report is
+  `mutations.md` and `mutations.json` in `--report-dir` (default the run's mutants folder). Not with `--suite`,
+  `--workers`, `--negative-control`, `--rerun-failures`, `--dry-run` or `--rebuild-fixtures`. Test:
+  `tests/mutate-command.test.ts`.
+- `test --workers <n> <feature…>` (backlog 34): the given feature files shared out among n workers that run at
+  once through `LabRuntime.runWorkers`, each with the variables the lab declares for its ports, state and caches
+  (`defineLab({ workers })`); each worker's output prefixed `[worker <i>]`, one line per worker at the end, the record
+  in `<report dir>/product-lab-workers.json` (default `.product-lab/test/workers-<time>`). Exit 0 only when every
+  worker passed and no two reached the same address. Refused with `--suite` or `--negative-control`.
+- `test --mode <name>` (config redesign, 6 October 2026): runs one of the lab's modes (`defineLab({ modes })`) as a
+  suite of its name, with the same options, output and reports as `--suite` (the record's `plan.mode` is true): one
+  row per combination of its environments, hosts, versions and devices (named by what varies; one combination is
+  one row named after the mode; `versions` takes `locked`, `latest`, `runtime-latest` and `hosts-latest`, the last two
+  moving only the runtimes or only the row's host), its tags, `onlyAffected` (changes to feature files only select
+  those files; with the mode's `scopes`, `{ glob: tags }`, a change under a glob selects its tag; any other code runs
+  everything; documentation nothing), `workers` (rows at once, each with the lab's variables for its
+  slot; one combination shared out by feature file) and `budget`. Never runs an old suite of that name; not with
+  `--suite` (`tests/suite-command.test.ts`, the fixture's `smoke`, `hosts`, `isolate` and `scoped` modes).
+- `test --suite pr|merge|nightly` (Phase 7): runs one of the lab's suites (`defineLab({ suites })`)
+  through `LabRuntime.runSuite`: `pr` (the affected scenarios of its tags, from `git diff` against
+  the merge base of `--base`, default `$PRODUCT_LAB_BASE` else `main`, plus uncommitted and untracked
+  files, or `--changed` paths; locked; within its budget), `merge` (every non-manual scenario,
+  locked), `nightly` (its matrix rows). `--plan` prints the rows and exits (1 when nothing would
+  run). Writes `product-lab-suite.json`, `junit.xml`, `report.html` and `summary.md` in the report
+  directory, each row's run in `<dir>/<row>`. Exit 0 only when the suite passed: a suite that selects
+  nothing fails and says why; unsupported rows are JUnit `<skipped>` and never count as passing
+  (`tests/suite-command.test.ts`, fixture `tests/fixtures/suite-lab`). The record's `counts` and
+  `timings` (rows by status; scenarios planned, executed, passed, failed, skipped, unsupported and not
+  reported; checkpoints; per row version resolution, run, each environment start with `cold`, `warm`
+  or `attached` as the environment declares it, reported step time and row total; planning, critical
+  path and total) appear in the HTML report (with each row's resolved combination), as JUnit
+  `<properties>` (`product-lab.*`) and in the Markdown summary (`src/reports/markdown.ts`,
+  `metrics-text.ts`). Nothing is estimated: a value the record lacks reads "not measured"
+  (`tests/suite-reports.test.ts`, with negative controls).
+
+`src/main.ts` (`cliRuntime`, `main`) is the process entry, the only file of this package that
+imports `@product-lab/composition`. `product-lab mcp` builds no runtime here: `main` runs it (`src/mcp-command.ts`,
+with the AI kit and release notices of `src/startup-notices.ts`) with only `@product-lab/composition/process`, so the
+server answers its client before anything else loads (`entrypoints/mcp/README.md`, "Start"); the composition root
+and `CliApp` load for every other command. `cliRuntime` resolves with the runtime. `main` builds one `LabRuntime` per invocation through
+`createLabRuntime`, from what the command line names (the lab, and whether it only inspects), and
+passes it to `CliApp` (`src/cli-app.ts`) with the composition root's `SyncCommandRunner` for bounded Git, tool and AI guard checks and `StdioWorker` for the MCP fd-3 worker. CLI source never starts a child directly. The
+CLI's runtime starts non-local environments too (the MCP server's does only with
+`--allow-public`). Both configuration shapes are accepted:
+
+- declarative `defineLab({ environments: {…}, apps: {…}, secrets, features, sessions })`
+  (see [`@product-lab/core`](../../core/lab/README.md#declarative-labs-phase-1)): validated and
+  compiled on load, relative paths resolved against the config's directory,
+  `--environment` selects a key of `environments` (default `defaultEnvironment`,
+  else the first);
+- legacy `defineLab({ name, start, environments?: [...] })`: unchanged.
+
+`product-lab host verify|fetch|build|rebase-check` (`src/host-command.ts`, `product-lab host --help`):
+`verify` runs the host conformance kit (`--only <ids>` narrows it) against a targets module
+(`--config <targets.ts>`), on the lab's environment with `--environment <name>` (its chains handed to the targets;
+started for the run and stopped after when none runs; a public network refused); `fetch` downloads and verifies an official truAPI CLI release or finds a
+patched host in the cache; `build` builds a patched host locally; `rebase-check --to <ref>` checks
+whether the adapter's patches still apply to another upstream commit without building, and exits
+with the adapter's code (0 applies, with any 3-way apply flagged "needs refresh"; 1 a conflict or
+skipped patch; 2 invalid input; the truAPI CLI's is described in
+[its README](../../adapters/host/truapi-cli/README.md#patch-rebase-check-product-lab-host-rebase-check-audit-g3-and-g4)).
+`build`, `rebase-check` and `fetch --patches` are for working on product-lab, in its checkout: in a product (an
+installed `@parity/product-lab`, `src/checkout.ts`) they exit 2 before anything loads, saying that a product runs
+released hosts only (`PRODUCT_HOST_TOOLS_REFUSAL`; `tests/product-hosts.test.ts`).
+`fetch`/`build`/`rebase-check` default to the
+host adapters the composition root constructs (`HOST_TOOL_KINDS` in `@product-lab/composition`,
+today `truapi-cli`, the default, and `dotli`), or `--config <tools.ts>` for a tools module of a consumer's own, so the CLI
+keeps no dependency on an adapter. Each host adapter factory's own flags and, for `fetch`/`build`/`rebase-check`,
+its `requiredFor` flags (exit code 2 when missing) come from that module.
+
+`product-lab env show [environment-id]` (`src/env-command.ts`, `@product-lab/cli/env`) resolves and
+prints a lab's topology; it needs a lab (`--config <lab.config.ts>`, or `./lab.config.ts`), because
+its profiles and adapter flags come from the lab's registered environment adapters
+(`defineLab({ environmentAdapters })` for the stock ones, `environmentFactories` for its own);
+`env show --help --config <lab.config.ts>` lists them. It is also described by `product-lab env
+--help`. The command parses the flags and layers them over the declared options; the report (text,
+`--json` manifest, what cannot start) is `ShowEnvironment`'s, the same as MCP `env_show`, with
+sensitive customizations redacted, and `--manifest` writes that redacted manifest (private,
+atomic).
+
+`product-lab init [--dir <path>] [--dev-server "<cmd>"] [--port <n>] [--ai] [--force]` (backlog 94, `src/init-command.ts`)
+sets the lab up in an existing app's repository and starts nothing. From package.json it reads the name and the dev
+script (`dev`, else `start`), run by the package manager its lockfile names, at the port its tool uses (Vite 5173, Next
+3000, else `--port`). A Vite script runs with `--host 127.0.0.1 --port <port> --strictPort` added on the lab's
+command line where the script does not name them: Vite listens on `localhost`, which is `::1` alone on some machines,
+while the lab reaches the app on 127.0.0.1 (found by the live proof of 4 October 2026). It writes the new layout (config redesign, 7 October 2026): `lab.config.ts` with only what is about the app (`app:
+{ label, steps, chains: ["people"], devServer }`, the chains and the settings marked TODO; the lab works out the
+environments, hosts, ports, readiness and funding), `lab/steps/<id>.ts` (`defineSteps`: one action, `{actor} opens the
+app`, and one assertion, `{actor} sees the app on screen`, wired to a test id the team names: TODO comments; an empty
+screen fails with the reason `screen-mismatch`), `lab/features/first.feature` (a new actor opens the app and sees it), `lab.lock.json` (examples/minimal's pinned polkadot-omni-node and People
+runtime, `src/init-lock.ts`), and adds lines to `.env.example` and `.gitignore` (`.product-lab/`) and the scripts `lab`
+and `lab:test` to package.json. The config's `defaultHost` is decided when `init` runs, from the truAPI CLI host's lock
+(16 October 2026; `src/cli-host-release.ts`, read through the runtime's `host fetch --list`, nothing downloaded):
+`"truapi-cli"` when the locked official release provides `localNetwork` (takes the lab's local endpoints), else
+`"truapi-wasm"`, the released truAPI WASM test host the package installs. The current 0.26.0 lock provides
+`localNetwork` and `navigationEvents`, so `init` writes `"truapi-cli"`. With an older lock lacking local routing,
+the config names the upstream change a local environment waits for. A release that cannot be read gives the WASM test host. The
+summary prints the default host; neither the config, the next steps nor `.env.example` mentions building a host. The generated files import the published package's subpaths (`@parity/product-lab`, `/composition`, `/browser-playwright`, `/ports/browser`: the packer's
+`umbrellaSubpath`). A file that exists, or a script of
+the same name with another command, is never overwritten without `--force`: the command lists them, writes nothing and
+exits 1. The “Next” installation, fetch, config and script commands use the same lockfile-based package manager
+as the dev server (the nearest lockfile in the app or an ancestor: bun.lock or bun.lockb, pnpm-lock.yaml, yarn.lock, otherwise npm), including with an explicit
+`--dev-server`. `--ai` also runs `ai init`. Bad flags exit 2 before anything is read or written. Tests:
+`tests/init-command.test.ts` (manager-specific next steps, explicit dev server, ancestor workspace lockfile; a Vite app's files and scripts, the config holding only the app (planted control: an `environments` line fails it); a second run refused with nothing changed; bad flags;
+the pinned lock equal to examples/minimal's; the generated lab typechecked and accepted by `product-lab lint` against
+the consumer subpaths, served from the workspace sources, with a type error and an unknown step as negative controls).
+
+`product-lab ai init|doctor|sync` installs and checks the AI kit for Claude Code
+and Codex (`src/ai/`, kit content in `ai-kit/`, which ships with the package);
+see [the package README, "With an AI assistant"](../../README.md#with-an-ai-assistant). Every other command reads the installed kit's record
+(`.product-lab-ai.json`, from the working directory up to the repository root; `src/ai/status.ts`) and, when it is
+from another version or has other content, prints one line on stderr naming both versions and `npx --no-install product-lab ai
+init`; `product-lab mcp` passes the same status to the server (`aiKit`, [the MCP README's Tools](../mcp/README.md#tools)).
+A missing or broken record says nothing (`ai doctor` reports it). The package's kit is loaded only once a record is
+found: inside this workspace loading it renders the references from `examples/notes` and `examples/minimal`, which
+every command (and every project whose tests start the CLI) would otherwise read. Tests: `tests/ai-status.test.ts`
+(the CLI line in a subprocess; no record, no load, with a record as its control).
+
+Version notices and `product-lab upgrade` (2 October 2026):
+`src/release/notices.ts` (`ReleaseNotices`) keeps, in `release-check.json` in the shared cache, the version each
+repository last used, the registry's dist-tags (asked at most once a day by `dev`, `test`, `fixture` and `mcp`, 3 s,
+`npm_config_registry` or npmjs) and the last version announced. Every command except `ai`, `upgrade` and `mcp` prints
+on stderr what is new since the repository's last used version (from the `CHANGELOG.md` the package ships; breaking
+changes first) and, on a terminal and at most once a day, a newer version; `--json`, `--help` and `--version` print
+none. `dev` passes the notice to the lab window, `mcp` to the server (`release` in the instructions and
+`lab_describe`). `CliApp.run` stops the check when the command is done (`ReleaseNotices.stop()`): the request is
+abandoned and its claim given back, so a slow registry never holds a finished command. Off in CI (`inCi`: `CI` or
+`CONTINUOUS_INTEGRATION` not `0`/`false`, or `BUILD_NUMBER` or `RUN_ID` set; an explicit `CI=false` wins), and for any package but `@parity/product-lab` (the workspace's own CLI never checks);
+`PRODUCT_LAB_NO_UPDATE_CHECK` or `NO_UPDATE_NOTIFIER` turn the registry check off. `src/release/upgrade-command.ts`
+(`product-lab upgrade [--to <version|tag>] [--dry-run] [--force]`) installs another version with the project's
+package manager in the `package.json` that declares it, refuses a dirty git tree without `--force`, then runs the new
+version's `ai init` and `fetch` (through the `SyncCommandRunner` port) and prints what is new. A failed pnpm install
+that pnpm's `minimumReleaseAge` explains (`pnpm config get`, the registry's publish time) is named, with when the
+version can be installed and the commands to finish by hand.
+The same daily check reads `productLab.minimumVersion` from the `latest` manifest: below it every command but
+`upgrade` and `ai` refuses to run, naming `npx --no-install product-lab upgrade` (`PRODUCT_LAB_ALLOW_BELOW_MINIMUM=1` runs it
+anyway). An installed version follows its channel's tag: `latest`, `next`, `canary` or `dev`.
+Tests: `tests/release-notices.test.ts` (the package, the registry and the commands are doubles) and
+`tests/release-exit.test.ts` (a child process against a registry that never answers; its control is never stopped).
+
+`product-lab test [feature...]` (`src/test-command.ts`, refactor step 8) runs a lab's feature files through
+`RunFeatures` over the `FeatureRunner` port: with a Cucumber configuration next to `lab.config.ts`, that
+configuration and its step files; without one (Phase 4, the bundled run), product-lab's own Cucumber, steps
+generated from the lab's registered sentences and the `step()` files its `steps` globs list, every feature not
+tagged `@negative-control` by default. `--negative-control` requires failure at one expected step. A lab that
+resolves a second copy of `@cucumber/cucumber` is refused. `tests/bundled.test.ts` runs a bundled lab end to end
+(fixture `tests/fixtures/bundled-lab/`: generated and custom steps, a malformed table and a wrong count as
+controls, a duplicate Cucumber refused). Scenario conditions (28 September 2026): the run's Cucumber, once its
+environment runs, skips every scenario with a tag that does not fit it (the lab's integrations' `scenarioConditions`),
+printing one line per such tag with the reason (`[product-lab] Not for this chain: <reason> (@tag); its scenarios
+are skipped`); the summary counts them (`4 scenario(s) (1 passed, 3 skipped)`), and a run in which every selected
+scenario was skipped ran nothing and exits 1 ("No scenario ran: every selected scenario was skipped …").
+`tests/scenario-conditions.test.ts` (fixture `tests/fixtures/conditions-lab/`). The environment starts inside the
+run, so the conditions cannot be read before it starts: the scenarios are skipped, not left out of the selection.
+
+- `versions [--available] [--json]`, `versions update [<component>…] [--to <selector>]`,
+  `versions pin <component> <version>`, `versions verify` (`src/versions-command.ts`): the lab's
+  version selectors (`defineLab({ versions: { policy } })`) against `lab.lock.json`, through the
+  `LabRuntime` versions methods.
+  `update` and `pin` write the lock all or nothing (exit 1 when a version does not resolve or the
+  lock changed meanwhile); `pin` refuses `latest-release`, `deployed` and `locked` with the
+  `versions update --to` command to use; `verify` exits 0 (verified), 1 (failed) or 2 (something
+  could not be fetched). A bare kind (`host`) names the lab's only component of that kind.
+- `versions propose --from <suite-dir> --row <candidate-row> --control <control-row>` (G2, 29 September 2026;
+  `LabRuntime.proposeLock`, `ProposeLock` in `@product-lab/application`): a lock proposal from the sealed execution
+  receipts of one `product-lab test --suite <name> --report-dir <suite-dir>` run. The candidate row's exact
+  resolution (a moving selector as the artifact it resolved to in that run, never resolved again) replaces the lock's
+  entries for its candidates, provided a control row of the same run ran the current lock and both passed. A dry run
+  by default: it prints the change, the rows with their run ids and receipt digests, and (`--body <file>`) writes a
+  Markdown pull request body naming the rows, versions, digests and run ids. `--write` writes `lab.lock.json` with the
+  lock's compare-and-swap; a lock changed since the suite ran is refused (`stale-lock`), as is one changed during the
+  write (`lock-conflict`). Exit 0 proposed, 1 refused, printing the refusal's code (`--json`: the typed
+  `LockProposalReport`); codes include `unsupported`, `failed`, `dry-run`, `no-receipt`, `receipt-digest-mismatch`,
+  `resolution-digest-mismatch`, `report-digest-mismatch`, `cross-suite`, `row-mismatch`, `run-mismatch`,
+  `incomparable-rows` (the full list is `LOCK_PROPOSAL_REFUSALS` in `@product-lab/domain/versions`). It opens no pull
+  request: that stays a separate step a person authorises. The receipts are local consistency checks, not an
+  attestation against a hostile producer (whoever can write the whole suite directory can forge a consistent one).
+  `tests/versions-command.test.ts`.
+- `--candidate <component>@<selector>` on `test` and `dev` (repeatable): versions resolve once at run
+  start, recorded as a run manifest whose path the run gets in `PRODUCT_LAB_VERSIONS_RESOLUTION`;
+  `lab.lock.json` is untouched. Split at the first `@` (`host:truapi-cli@git:host-rust-core@c7449d3a`).
+
+`product-lab config [<group or key>] [--config] [--json]` (`src/config-command.ts`, config redesign, 6 October 2026)
+prints the config as the lab runs it, starting nothing: `LabRuntime.registry().config` (the loader's resolved config,
+`ResolvedLabConfig`), grouped and worded by `@product-lab/domain/lab/resolved-config` as the lab window's Config view
+shows it (App, Environments, Hosts, Modes, Checks, Lab, Advanced). Each value says where it came from (`yours`: written
+in lab.config.ts, with its line when known; `default`: the lab's rule, with why; `detected`: read from the product;
+`advanced`: a definition field given under `advanced`), its key, the line that changes it and the other values it
+takes. A group id or a key narrows it; `--json` prints the resolved config. A value from a secret shows its variable's
+name only. Exit 1 when the lab gives no resolved config or the filter names nothing. Tests:
+`tests/config-command.test.ts` (fake runtime; control: no config), `tests/config-command-lab.test.ts` (a product config
+through `createLabRuntime`, a planted phrase never printed).
+
+`product-lab lint [--config] [--environment <id>] [--strict] [--cucumber <file>] [--json]` (`src/lint-command.ts`,
+Phase 4) checks a lab through `LabRuntime.lint` (`LintLab`) without starting anything: a lab that does not load (one
+error per problem the loader lists, such as a step group listing a function), a second `@cucumber/cucumber`
+installation or a step file that does not load, and every feature scenario's plan (one scenario per Examples row, the
+Background first): missing or ambiguous sentences, malformed tables, actors not introduced, dangling references,
+invalid literal inputs are errors; a block unavailable in an environment is an error for `--environment`, else a
+warning per environment; custom `step()` definitions are warnings; a scenario tagged `@negative-control` only warns.
+With the lab's own Cucumber configuration a step nothing matches may be hand-written: a warning unless `--strict`.
+Since Phase 5 every declared UI module passes the client-bundle check the panel runs before serving it (rule
+`client-bundle`): a module importing a package or a file outside its UI folder, or holding one of the lab's secret
+values, is an error (the secret is never printed). Exit 1 on any error. `tests/lint.test.ts` (fixture `tests/fixtures/lint-lab/`, and `bundled-lab`) holds its
+controls (`lab.ui.config.ts` and `ui/`: three UI modules that must fail the client-bundle check, one clean).
+
+`product-lab coverage [--config] [--cucumber <file>] [--controls] [--json]` (`src/coverage-command.ts`, backlog 44)
+reads `LabRuntime.coverage` (`CoverageLab`) from the same plan `lint` checks, without starting anything: every
+registered sentence with the scenarios and steps that use it, counts per kind (the integrations' actions, assertions,
+repeatable sentences, step groups and run-together groups first, then the framework's own), the integrations' unused
+sentences apart from the framework's own (`lab.…`), and the steps no sentence matches. A step group or a repeat counts
+for itself and for each sentence it expands into, once per step. `@negative-control` scenarios count only with
+`--controls`. Exit 0 with a report, 1 when the lab does not load. `tests/coverage.test.ts` (fixture `bundled-lab`).
+
+`product-lab explore` (`src/explore-command.ts`, backlog 39) starts the environment and calls `LabRuntime.explore`
+(`ExploreLab`): seeded random samples of the lab's actions with every declared invariant checked after each step, the
+first failure shrunk, written as Gherkin and confirmed ([the package README, "When a check fails"](../../README.md#when-a-check-fails)).
+It writes `report.json` and `minimal.feature` to `<lab>/.product-lab/explore/<run>/` (or `--report-dir`); `--save <dir>`
+saves the feature as `<dir>/explored-seed-<n>.feature` through the runtime (`LabRuntime.saveExploredScenario`, the same
+save as the lab window's "Save as a feature"): `-2`, `-3` beside a file already there, refused outside the lab's
+directory, and removed again (with a folder made for it) when the lab's features globs would not list it; a refusal
+says why (on stderr with `--json`). Exit 0 no failure, 1 a failure (confirmed, flaky or blocked), 2 a
+usage error. `tests/explore-command.test.ts` (fixture `explore-lab`: a planted fault, its fixed control, an action
+declared `explore: false`).
+
+`product-lab what-if <feature>` (`src/what-if-command.ts`, backlog 21) starts the environment and calls
+`LabRuntime.whatIf` (`WhatIfLab`): the feature's Background once, each scenario or outline row from its saved state
+([the package README, "Commands"](../../README.md#commands)). It prints and writes (`report.json`,
+`report.md` under `<lab>/.product-lab/what-if/<run>/` or `--report-dir`) the trunk's one-time cost, each branch's
+result, checks and times, the checks per branch and what differs. Exit 0 when every branch ran, 1 for a failed trunk, a
+branch not planned or not run, or a refusal (an environment without save and restore says how to get one), 2 for a
+usage error. `tests/what-if-command.test.ts` (the refusal on the in-memory `explore-lab`, the Markdown).
+
+`product-lab --help` lists the command families; `dev --help` and `check --help`
+show only the options their command uses. `dev --scenario` preselects a scenario
+in the panel without starting it. `--headless`, `--video`, `--synthetic-media` and `--cursor` apply to the lab window, so not with `--browser`.
+The implemented `fetch` and `doctor` commands are described under Locked setup artifacts below.
+
+## Package
+
+| | |
+| --- | --- |
+| Nx project | `cli` |
+| Tags | `scope:core`, `layer:cli`, `type:driving` |
+| Exports | `.` (`src/cli-app.ts`: `CliApp`, `runtimeOptions`), `./main` (`src/main.ts`: `main`, `cliRuntime` (resolves with the runtime), the process entry `bin/product-lab.mjs` imports), `./dev` (`src/commands/dev.ts`: `startDev`, `dev`, `LabStopError`; `DevOptions.terminalApp` shows the terminal app, `DevOptions.session` one the caller already opened, `insideTerminalApp` runs work with it on screen and shows a failure in it, `ShownFailure` is such a failure; `DevOptions.progress` takes a `StartProgressView`, `DevOptions.env` the variables; the flags' mode is `labWindowMode` in `src/lab-flags.ts`, not exported), `./env` (`src/env-command.ts`: `runEnvCommand`, `envUsage`, `overridesFromFlags`), `./test` (`src/test-command.ts`: `runTestCommand`), `./kit-reference` (`src/ai/kit-reference.ts`: `KIT_REFERENCES`, `writeKitReferences`, `referenceSources`, `PRODUCT_REWRITES`, `forProduct`, the renderers; the packer and the release check use it); bin `product-lab` (`bin/product-lab.mjs`; without installed dependencies it exits 1 naming `bun run setup`) |
+| Depends on | `@product-lab/composition`, `@product-lab/domain`, `@product-lab/mcp`, `@product-lab/ports`, `@product-lab/shell`, `tsx`, `smol-toml`, `yaml`, `ink` 8.0.0 and `react` 19.3.0 (the terminal app), `@types/react` 19.3.0; dev/test only: `@product-lab/contract-host`, `@product-lab/core`, `@cucumber/cucumber`, `ink-testing-library` 4.0.0 |
+| Used by | every example, `tools/verify`; `./kit-reference` by `tools/eval` (packing) and `tools/release` (the tarball check) |
+| Never depends on | an adapter (`type:driving` may not depend on `type:adapter`): host tools and verification targets are loaded at run time from a path. The composition root constructs every adapter; only `src/main.ts` imports it, and no entry point source imports `@product-lab/application` |
+
+Console redaction (backlog 89): `src/main.ts` sends every console line of the invocation through the runtime's
+redactor (`redactConsole` from the composition root), so a lab or provider that prints a secret of the lab (a
+`fromEnv` RPC URL with its token) shows it as `[redacted]`; a bundled `product-lab test` run's process does the same
+(`featureRuntime`). `tests/secret-console.test.ts` (fixture `tests/fixtures/secret-console-lab`: the terminal and the
+run's files) and `tests/rpc-flags.test.ts` (`dev` over `tests/fixtures/rpc.lab.config.ts`).
+
+Environment variables: `src/main.ts` passes the process's (`NodeSystem.environment`, the `EnvironmentVariables` port)
+to `CliApp` (its fourth argument), which hands them to the commands: `dev` (`DevOptions.env`: `CI`, `TERM`,
+`NO_COLOR` for the progress view), `test --suite` (`runTestCommand`'s fifth argument: `PRODUCT_LAB_BASE`) and
+`doctor` (`PRODUCT_LAB_HOST_BIN`). No file under `src/` reads `process.env`; a programmatic caller that passes no
+variables gets every default (`src/environment.ts`, `tests/command-environment.test.ts`). Only
+`bin/product-lab.mjs` reads `NODE_OPTIONS` itself, before anything loads, and in a terminal it sets `ESBUILD_BINARY_PATH`
+and `PRODUCT_LAB_ESBUILD_BINARY` for tsx's own esbuild, then removes both before the CLI starts anything
+(`bin/esbuild-session.mjs`, lane E2): tsx's esbuild service runs through `bin/esbuild-own-session.sh` (setsid, or perl's
+`POSIX::setsid` on macOS) in a session of its own, so it is never the terminal's foreground process and the title
+names the lab, not "esbuild". It has tsx transform one new file first, so the service starts then (about 0.2 s);
+without a terminal, on Windows, with `ESBUILD_BINARY_PATH` already set, with a wrapper that cannot run (a lost mode) or without setsid or perl, nothing changes
+(`tests/esbuild-session.test.ts`).
+
+`ai-kit/` is the consumer AI kit's content (skills, subagents, the AGENTS.md section, the MCP
+registration) that `product-lab ai init` installs; `src/ai/` renders it and, for this repository,
+renders `ai/` (`ai sync`) and puts the consumer kit in every example lab (`src/ai/examples.ts`: what `ai init` installs,
+its MCP server on the example's own lab from this repository's CLI, and an `AGENTS.md` that puts using product-lab
+first). Every Codex MCP table it writes sets `startup_timeout_sec = 60`.
+
+Tests: `bunx nx run cli:test` (`tests/run-tests.mjs`: every test file, or with `CLI_TEST_SHARD=<index>/<count>` one share of them, as CI's three CLI runners run them; `node tests/run-tests.mjs plan 3` prints the shares). The fixture labs share `tests/fixtures`, so each test file keeps its labs' running-lab record in a directory of its own (the preload `src/own-running-record.ts`, also the examples' as `@product-lab/cli/own-running-record`: `PRODUCT_LAB_RUNNING_DIR`); `tests/running-record.test.ts` shows the guard still refuses two labs of one folder without it. The lab journey: `tests/lab-flags.test.ts` (each flag's mode, the contradictions and
+the unknown-flag message) and `tests/visible.test.ts` (the process: `--headless` starts only headless browser
+processes, `--browser` starts none, HTTP runs are not refused, Watch over HTTP is, unknown and contradictory flags exit
+before the lab loads). Typed decisions: `tests/typed-errors.test.ts`
+(`host --help` with a missing `--config` module reads the domain's `MissingHostToolsError`, `lint` lists a
+`LabConfigurationError`'s `problems`; a plain Error with the same message is not taken for either); an unknown
+option's name comes from `src/parse-args-errors.ts` (`unknownOption`, the classifier of node:util `parseArgs`'s
+error, listed in `ERROR_CLASSIFIERS`). `tests/partial-of.ts` gives the tests' partial doubles a checked type (`partialOf<T>`, one single
+assertion) instead of double type assertions (q10-types).
+
+## Locked setup artifacts
+
+`product-lab fetch --config <lab>` fills the shared cache from the lab’s lock. `product-lab doctor --config <lab>` reports cached artifacts, the hosts and Playwright's full Chromium executable without starting a chain or browser.
+The runtime's browser prerequisite port asks the selected launcher for the executable, revision and matching installer;
+this entry point neither imports Playwright nor resolves its modules. Missing Chromium fails both text and JSON.
+Checkout remediation is `bun run setup`; a consumer gets the adapter's quoted installer command with its exact Node/Playwright CLI paths and effective browser cache,
+so another Playwright version in the app cannot select the wrong browser revision. An unavailable inspector fails
+explicitly with a package/inspector remedy, kept outside any shell command chain. The checkout's “in your own repository” hint runs doctor there to obtain that repository's matching browser installer. This checks executable-file access, not whether the OS can launch it.
+`tests/product-hosts.test.ts` covers the real isolated installation, empty browser cache, text/JSON and checkout hints.
+
+In product-lab's checkout `doctor` also checks Bun and the patched truAPI CLI host, and its fix is `bun run setup`; in a product (`src/checkout.ts`: the package root's `package.json` is not the workspace's) it checks the truAPI WASM test host the package installs (`@parity/truapi-host`, found as Node finds it), reports the truAPI CLI host's locked official release (`host fetch --list`: the release, cached or not, what it provides, and whether it runs local environments or live networks only, with the upstream change it waits for; a note, never a failure: a session downloads it; `src/cli-host-release.ts`), needs no Bun, and names `npx --no-install product-lab fetch` for missing cached artifacts, combined with the matching browser installer when Chromium is missing (`tests/product-hosts.test.ts`).
+
+Since 16 October 2026 `fetch` also prepares what the lab's environments need on this machine and never make themselves
+(`LabRuntime.prepareEnvironmentTooling`; the environments declare it as `EnvironmentProvider.tooling`): the Engine
+checkout a local copy of a network (`paseo-copy`, `previewnet-copy`) starts from, cloned, patched and built once in the
+shared cache (`<cache>/engine`, the folder the saved forks read). Only the lab's default environment's tools and those of
+each `--environment <id>` (repeatable; `all` for every one) are prepared and fail the fetch when missing; the others are
+listed as notes with the command their first start names. That is a choice, not the simplest rule (prepare whatever the
+config offers): a product's config offers `paseo-copy` by default, so every `fetch` (CI's included) would clone and build
+Engine, about 900 MB and a few minutes, for labs that only run the local dev chain, and would fail on a machine without
+Git or GitHub access. `--engine-repository <url|path>`, `--engine-ref <ref>` and `--no-engine-patch` (stock Engine,
+recorded as such) name another Engine; given when no required environment starts from Engine, they are refused (exit 2)
+rather than ignored. `--json` adds `environmentTooling` to the report and keeps Engine's build output off stdout.
+`doctor` reports the same tools (`tooling:engine`), required for the default and each `--environment`, a note otherwise,
+and in a product its fix names the environments (`npx --no-install product-lab fetch --environment paseo-copy`).
+Since 27 October 2026 `doctor` also checks the Engine build the shared cache holds against the release this product-lab
+pins (`cache:engine`; the composition root's runtime checks it with env-engine's `preparedEngine` as its own `cachedTooling`, off the `LabRuntime` port), whatever the lab declares and
+whether or not it loads: a cache copied from one that held the retired patched Engine passed the doctor and refused at
+environment start. Another build (the retired patch, another commit, an `--engine-ref` build, a missing or non-empty
+patch digest, a record over a checkout that is not that build) names the build held and the pinned one. It fails where
+the lab would start from it, as the `tooling:engine` line does: an Engine tool required by the default environment or an
+`--environment`, and, in the product-lab checkout, a lab that declares no Engine tool (an example may start Engine
+itself, undeclared). Elsewhere it is a note: a lab whose Engine environments are not asked for (the quick journey's), or
+a product whose lab starts nothing from Engine. The fix: `bun run setup` in the checkout (it keeps a cache's Engine at
+the pin with or without the private example submodule), else `npx --no-install product-lab fetch --environment <the
+Engine environment>` (with `--config` when doctor had one).
+Each also names the other way out: point `PRODUCT_LAB_CACHE_DIR` at a cache prepared for the pin. A cache holding no
+Engine has no line, as before. Read-only: it reads `engine-build.json` and, for the pinned build, the checkout's HEAD (`tests/environment-tooling.test.ts`).
+A fetch
+whose lab does not load still fetches the locked files and says the tools were not checked
+(`tests/environment-tooling.test.ts`).
+
+`doctor` then says what fits this machine (`src/machine-fit.ts`, config redesign, 6 October 2026), from its cores,
+memory and the free disk under the shared cache. Each line is informational and never changes the exit code; `--json`
+has it as `fit`.
+
+| Line | What it says | Where the number comes from |
+| --- | --- | --- |
+| `machine` | Cores, memory, free disk | `availableParallelism`, `totalmem`, `statfs` of the cache (or its nearest existing parent) |
+| `people at once: fast` | How many people the local dev chain takes at once | About 1 GB each (a Chromium page, 0.8 GB as an upper bound from RSS, and a host process) beside 1.5 GB for the chain and 3 GB for the system: estimates until the nightly laptop job measures them |
+| `<the lab's copy>` (`Local copy of Paseo`) | Full or Light: the option the lab would start now and why (the person's last choice, else this machine's fit, as `product-lab check` and the window pick it), and each option that does not fit with its needs | The registry (`LabRuntime.registry`); Full needs 8 cores and 16 GB, measured |
+| `people at once: <copy>` | People at once on that option | Its measured peak with two people (Full 6.7 GB, Light 5.2 GB), then 1 GB each |
+| `disk`, `disk: network copy` | Shown only when short: a run needs about 2 GB, a copy's first start about 10 GB (its saved state is 3.6 GB) | |
+| `cache` | Set up, or what is missing (the locked files, the host) | The checks above |
+
+A lab with no local copy of a network says so. Tests: `tests/machine-fit.test.ts` (a 4-core 8 GB laptop, a 16-core
+48 GB machine, the person's own choice that does not fit, no copy, low disk, a missing cache). Every CLI invocation loads optional `.env` files from the lab directory to the workspace root (shell wins, nearer file wins). `node --import tsx --import @product-lab/cli/load-env <script>` gives direct scripts the same behavior. `--import @product-lab/cli/own-running-record` gives a test or e2e script that serves a lab window a running-lab record of its own (`PRODUCT_LAB_RUNNING_DIR`, a temporary directory), so two such scripts of one lab run side by side; a person's lab never uses it. Since 6 October 2026 it also keeps a
+`node --test` child's standard output for the test runner (`src/test-output.ts`, also `@product-lab/cli/test-output`):
+there `console.log`, `console.info` and `console.debug` write to standard error, as `startDev`'s progress does, because a
+line in the runner's stream could end the run with "Unable to deserialize cloned data due to invalid or unsupported
+version" (guard: `tests/test-output.test.ts`).
+
+## Summarize a suite run
+
+`product-lab report summary <run> [--markdown | --json]` prints one suite run (its report directory or
+`product-lab-suite.json`) as the Markdown summary (default) that `test --suite` also writes as
+`summary.md`, for a CI job summary or a pull request comment (`tools/ci/suite.sh` uses it); `--json`
+prints the record's counts and timings. A directory without a suite record exits 1; a usage error
+exits 2 (`tests/suite-command.test.ts`).
+
+`product-lab report comment <run> [--recordings <dir>] [--label <text>] [--run-url <url>] [--artifact <name> |
+--video-base <url>] [--out <file>]` (backlog 52) prints a suite run's pull request comment (`src/reports/pr-comment.ts`):
+the marker `<!-- product-lab:pr-suite -->` that makes it self-replacing, the verdict and reason, then one row per
+scenario with its row, result, time and, from its recording in `--recordings`, where it is in each identity's video. A
+recording is matched by its feature run, or by its title and a start inside the row's run (a Cucumber process's
+recordings name no run); the latest wins. With `--artifact` a video's place is text ("starts at 0:42 (to 0:47)"): an
+artifact is a zip and nothing can seek into it. Only with `--video-base` (a direct address serving `videos/`) is a
+video a link that seeks (`#t=42,47`). "no recording" and "no video (run without `--video`)" are said, never left
+blank. It loads no lab. `pr-suite.yml` posts it. Test: `tests/pr-comment.test.ts`.
+
+## Recorded runs
+
+`product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60] [--format mp4|webm] [--plan | --slide-only] [--failed] [--json]`
+(backlog 36) cuts a recorded feature scenario into a demo through `LabRuntime.demo`: about a
+minute, each action at real speed with its result held, waits sped up and labelled, a caption per Gherkin step in the
+lab window's style, with `demo.vtt`, `demo.json` and a slide (`slide.png`, `slide.html`) in
+`<lab>/.product-lab/demos/<recording-id>`. The video needs `ffmpeg` and `ffprobe` on `PATH` (or `PRODUCT_LAB_FFMPEG`
+naming their folder; never bundled); `--plan` and `--slide-only` do not. Starts nothing. Exit 2 when refused (no such
+recording, no video, a failed run without `--failed`, no ffmpeg) or on usage errors. Tests: `tests/demo-command.test.ts`.
+
+`product-lab journeys [--out <dir>] [--tag <tag>]... [--all] [--dry-run] [--json]` (backlog 47,
+`LabRuntime.journeyDocs`) writes a user walkthrough per scenario tagged
+`@journey` (or the lab's `journeys.tags`): `<out>/<scenario>/README.md` with each step's screenshot of the identity that
+acted and captions stating only what its newest passed recording proves, and an index `<out>/README.md` (default
+`<lab>/.product-lab/journeys`, git-ignored). A failed run never replaces a page; a scenario without a passed recording is
+skipped with why. It refuses to write over a file it did not write. With `journeys` declared in `lab.config.ts`,
+`product-lab test` rewrites them after its run (`src/journeys-after-test.ts`; a failure to write is reported and never
+changes the exit code). Tests: `tests/journeys-command.test.ts`.
+
+`product-lab recordings [<id>] [--step <n> | --timings] [--json]` (Phase 9)
+lists the lab's recorded runs, newest first (status, identities, steps, frames captured, unavailable and failed), or
+prints one recording's replay timeline: each step's identity, outcome and time, the frames before and after it with a
+note on their timing or why they are missing, the step's transactions and the chain heads the lab had observed. It
+loads the lab and reads the store only: nothing starts or runs, and it works after the environment stopped. Where
+recordings go and how long they stay: `PRODUCT_LAB_RECORDINGS` (`frames` default, `steps`, `off`),
+`PRODUCT_LAB_RECORDINGS_DIR` (default `<lab>/.product-lab/recordings`), `PRODUCT_LAB_RECORDINGS_KEEP` (50),
+`PRODUCT_LAB_RECORDINGS_MAX_AGE_DAYS` (30), `PRODUCT_LAB_RECORDINGS_MAX_MB` (500), `PRODUCT_LAB_RECORDINGS_VIDEO` (`off`
+default, `on`: `test --video`; the videos in `videos/` are removed with the last recording that names them, and are
+not counted in the size limit), `PRODUCT_LAB_RECORDINGS_HOST_LOGS` (backlog 192: `failed` default, `always`, `off`: each
+host's own log is kept with a failed run's recording as `hosts/<person>-<host>.log`, redacted) and
+`PRODUCT_LAB_RECORDINGS_HOST_LOG_KB` (2048: the most of one log kept, its tail). Exit 2 on usage errors. Test:
+`tests/recordings-command.test.ts`.
+`--timings` (backlog 29, `LabRuntime.recordingSpeed`) prints each step of the recording against the same step in
+earlier passed runs of the scenario (same lab and environment): `SLOWER` when it took more than twice its median and at
+least 2 s more, `no history` with fewer than 3 earlier runs, `not timed` without a duration; `--factor`,
+`--min-gap-ms` and `--min-samples` change the limits.
+Since backlog 22 a step also shows what it changed on each chain (`chainChanges`): its block window and event count,
+with the steps it shares blocks with; under `--step` the events (and the scenario accounts they mention), the acting
+identity's nonce and free balance before and after, and the gaps.
+Since backlog 23 a step shows what its identity's app printed (`console: N error(s) (M unexpected), K warning(s)`; the
+messages under `--step`), and the header names each app whose console was not watched; since backlog 41 what the step's
+apps asked their hosts (`asked its host (<app>): …`, or why it is unknown);
+since backlog 25 a step's health findings (`health:
+machine overloaded: …`, a chain without a new block, lagging finality; the machine and chain numbers under `--step`), and
+the header gives the samples taken and what could not be sampled;
+since backlog 241 the header also names the steps the machine
+held back and those the lab's own loop did, each step's finding says how (`the machine was the limit: its CPUs were 4 %
+idle (load 11.0 on 10 CPUs)`, `the lab's own loop was the limit: it was busy 95 % of the time and answered up to 1.4 s
+late`), and `--step` adds the CPUs' idle share, the memory pressure and the loop to the machine line.
+
+`product-lab bundle <recording-id> [--out <file>]` and `product-lab bundle open <file> [--dir <directory>]` (backlog 20,
+3 October 2026) write a recorded feature scenario as one run bundle and open one read-only, through
+`LabRuntime.runBundles()`. A bundle is one `<id>.plbundle` (a zstd-compressed tar any `tar --zstd` opens) holding the
+recording, the feature file as it ran, the lab lock, the run manifest and the fixture the scenario started from, with
+every file's sha256. `bundle` prints the file, the
+verdict, the starting state, what was withheld (an identity whose key comes from a lab secret) and every reason it
+cannot be reproduced; `bundle open` prints the run's steps, the failure and its stable marker, and every reason it
+could not be reproduced here (another platform with native state, other app or lab source, a changed feature file, a
+public network, unsaved state). Neither starts anything. Exit 2 on usage errors. Test: `tests/bundle-command.test.ts`.
+
+`product-lab reproduce <bundle.plbundle> [--reruns <n>] [--against-current] [--confirm <token>]` rebuilds a bundled failing run here:
+the bundle's fixture imported (or the environment started fresh), the same scenario run in this process at its line,
+and the rerun judged against the bundled failure by the negative-control rule (the same step, the error's stable
+marker: "reproduced"). What cannot be rebuilt is refused before anything starts, naming every reason (`bundle open`'s
+list); `--against-current` accepts other app, lab or feature source and reports a recheck, never a reproduction. A
+bundle holding every run is written beside the extracted one, and the environment it started is stopped.
+`--reruns <n>` (backlog 26) reruns up to n times, each from the same rebuilt state, stopping at the first rerun that does
+not fail: the verdict is then `flaky`, which exits 1 like any failure. Exit 0 when
+reproduced (or the same failure on a recheck), 1 otherwise or refused, 2 on usage errors. Test:
+`tests/reproduce-command.test.ts`. Live on Notes, with an in-process run and a `product-lab test` run.
+
+`product-lab bisect <previous> <current> [--change <key> | --row <id> --scenario <name>] [--runs <n>] [--max-probes <n>] [--budget <minutes>] [--out <dir>] [--dry-run]`
+(backlog 37) finds where a regression `report compare` found came in: the two suite runs' changed app, runtime or host
+component is the axis, each probe runs the one scenario as its row ran it, and the ends run again first. It prints
+`summary.md` (the verdict first, then every probe, then one shell command that reruns the first bad value; for the
+lab's source it runs from the repository's top: a worktree at the commit, a frozen install, the run from the lab's
+directory) and writes `product-lab-bisect.json` to `--out` (default `.product-lab/bisect/<time>` in the lab's
+directory). What cannot be bisected is refused by name. Exit 0 when it found the first bad value or planned a dry run,
+1 otherwise, 2 on usage errors. Test: `tests/bisect-command.test.ts`. It was run live on a planted regression in Notes.
+
+## Compare saved suites
+
+`product-lab report compare <previous> <current> [--out <dir>] [--notify-dir <dir>] [--json]` compares saved suite directories or their `product-lab-suite.json` files. It writes HTML, Markdown and JSON into `<current>/compatibility` by default. The optional notification directory receives deduplicated Markdown/JSON messages and `sent.json`; no message leaves the machine. Exit 1 means regression, new failure or lost coverage; exit 0 includes recovery/unchanged results; exit 2 indicates usage errors. Attribution is based on recorded changes and cross-row evidence, not an independently proven cause. Test with `bunx nx run cli:test`.
+
+The generated consumer Notes reference includes the explicit persistent workspace config and its private actor-store helper, the local Chopsticks upstream and saved Paseo fork providers, plus the original optional TSX account panel and fixed React helper preparation script. The reference explains preparation before check/lab and classic JSX typechecking; generated helper bytes are not embedded. The same script renders the minimal reference (every file of `examples/minimal` a consumer needs, with the command that runs its negative control). Both run a product's people on the released truAPI WASM test host (8 October 2026): `PRODUCT_REWRITES` changes the examples' default host and their modes' hosts from the truAPI CLI host, which runs a product's local environment only when its locked release takes the lab's local endpoints (#1166; the locked 0.26.0 does, and the WASM test host runs everywhere), and Notes' config keeps one fixture (`two-writers`, its setup shipped) of its four; each rewrite matches its example exactly once or fails the render; `cli:test` fails when a shipped feature or config names the CLI host, or a shipped config names a fixture setup the reference does not carry (`tests/kit-reference.test.ts`). Neither is committed (backlog 147): `KIT_REFERENCES` names where each sits in the kit (`skills/product-lab-integration/references/notes-lab.md`, `skills/product-lab-setup/references/minimal-lab.md`, both under `ai-kit/`), the packer writes them into the packed kit (`writeKitReferences`, from `tools/eval/src/pack.ts`), and `loadKit` renders them in memory when the kit sits in this workspace, so `ai init` from source installs the current ones. Nothing to regenerate after a Notes or minimal change; to read one, `node --import tsx entrypoints/cli/src/ai/kit-reference.ts --out <dir>`. Such a change ships, so it needs a changeset naming `@parity/product-lab` (`referenceSources`, which `shippedPaths` counts). The list must be closed under relative imports: `unlistedNotesImports` names any file a listed Notes file imports that the list omits (generated `lab/ui/dist/` excepted), and the generator and `cli:test` refuse such a list (`lab/cleanup.ts` and `lab/vite-build.ts` were missing until 29 September 2026). `cli:test` lists `examples/notes/**` and `examples/minimal/**` as Nx inputs (`package.json` `nx.targets.test`), so a Notes change always reruns the reference checks instead of reusing a cached pass.
+
+The bundled-run and scenario-condition tests use fresh temporary recording directories for each CLI run,
+so prior fixture recordings cannot affect their result.
+
+HTML, Markdown and JUnit reports show host-bypass evidence per scenario and step, including each app's policy and written allowance reason, direct connections, every finalized ledger entry and every coverage gap. This evidence is never clipped by the ordinary HTML attachment size limit. Recording text shows the same run and step evidence; absent evidence is coverage unknown.
+
+In `report.html` each host-bypass block is closed by default (backlog 148, 6 October 2026). Its summary is the lab window's host check headline ("Host check: Nothing went around the host", "Host check: Found 2 sent around the host · not complete: …", from `@product-lab/shell/host-bypass-words`), then why, the findings, the explained kinds and each person's app and traffic in words, and the full raw lines below them. The host-bypass heading includes an aggregate verdict: an unexplained foreign extrinsic warns even when individual apps are clean. Strict failures, incomplete coverage and stricter stored verdicts remain visible without assigning the foreign transaction to an app.
+
+A generated step that times out can print an additional `After aborting step` diagnostic
+when its action finishes unwinding during scenario cleanup. Its last error is also kept
+in the failed step's separate `abortDetail` field and displayed in HTML and JUnit reports. The timeout remains the
+failure; this detail does not change retries or cancellation. Test:
+`tests/abort-diagnostics.test.ts`.
+
+The generated minimal reference uses the released SDK's native PAPI 3 transaction creator and carries its app's current SDK and client install pins. Its file list and dependency test follow that source; no local signer bridge is copied. The rebased migration is awaiting qualification.