Design and internals

The rest of these docs say what the bench does. This chapter says how it is built and why — for contributors, and for anyone debugging behaviour that only makes sense once the mechanism is visible.

Two constraints shape nearly everything here.

Several processes look at one bench at the same time. A CLI command you type, the Qt console, the headless fleet run, the remote agent — each must be able to answer is pm100d running?, what did that install print?, why did the server die? about processes another one started, possibly yesterday. So every piece of bench state is a small file in the home, and nothing the bench manages is a child process of the thing that started it.

Benches are Windows, developer machines are not. The same code runs on both, and nearly every bug this component has had was platform-specific. So every platform branch lives in one module, and a test fails if one appears anywhere else.

The pages

  • Architecture — the layers (model, services, presenter, view, host), what each may depend on, the home layout, fleets, where a device writes, and how one request travels through them.

  • Process management — why nothing is a child process, what the detached launcher does, how liveness and exit codes survive the process that started them, and the stop sequence.

  • Ports — the reserved numbers, where a port comes from, the difference between a named and an allocated port, and why allocation asks the socket rather than the bookkeeping.

  • The installer — how an installed version is matched to a declaration, the staging directory, the fallbacks for a release that is not on the index yet, and where git comes from.

  • The agent and the client — the wire protocol, why the CLI is the API, the one request type that is not a command invocation, and the split into two distributions.

  • The console’s design — what is taken from plesty-lib and what is designed here, how the view stays a view, and how it is tested offscreen.

  • Experiment runs — the manifest, how Run checks the shared disk and serves devices across benches, how a run is watched and stopped through its directory, a run whose job died, operators and notes, the welcome demo, and how its report is written.

  • Cross-platform development — the one-module rule, the full table of what differs, and how to add a difference.

  • Packaging and releases — the two wheels, the light installers, updating from the app, the CI jobs on a tag, signing, and the uninstall design.