Split matrix selection: run takes --interpreter, prepare-envs takes --env (ADR-0103)

`--env` and `--interpreter` both existed on `run` and `prepare-envs`
and intersected in ways callers could not predict: a base named by
`--env` silently ignored its `default_interpreters` policy, and
`--interpreter` on prepare-envs widened or narrowed every matrix base
at once. Each command now has one selector, matching what it operates
on: `run` fans out over interpreters, `prepare-envs` over envs.

- `run` selects by `--interpreter` only; `all` means the full axis and
  ignores `default_interpreters`. `--env` is removed from `run`.
- `prepare-envs` selects by `--env` only, in four forms: `<base>` (the
  base's default subset), `<base>@<impl>-<version>` (one child),
  `<base>@all` (every child) and a non-matrix env name. `--interpreter`
  is removed from it.
- With any `--env` given, a base not named contributes nothing; without
  one, every base applies its own default policy. Each base's policy
  selects its own children only.
- Rework env_selection around resolve_run_selection, which yields
  concrete selected envs, and pass them down through matrix_runner and
  matrix_streaming via selected_variants so both fan-out paths filter
  identically.
- Update CLI docs, the preparing-environments guide, WM internals and
  protocol docs, and the unit tests.

Author: Aksem

docs/cli.md

@@ -64,14 +64,13 @@ python -m finecode run [options] <action> [<action> ...] [payload] [--config.<ke
 | `--no-save-results` | Do not write action results to the cache directory |
 | `--results-file=<path>` | Also write *this run's* results to `<path>`, unmerged, on every exit path, and report the path on stderr. See [Per-run results file](#per-run-results-file) |
 | `--dev-env=<env>` | Override the detected dev environment. One of: `ai`, `ci`, `cli`, `ide`, `precommit` (default: auto-detected — see [Dev environment detection](#dev-environment-detection)) |
-| `--env=<name>` | For a matrixed action (ADR-0047), restrict execution to the named interpreter environment(s) — a matrix base selects all of its children, a concrete child selects only itself. Repeatable. Non-matrix envs are unaffected. See [Preparing Environments — filtering by environment name](guides/preparing-environments.md#filtering-by-environment-name). |
-| `--interpreter=<impl>@<version>` | For a matrixed action, restrict execution to the named interpreter(s) across every matrix env the action touches. Repeatable; a bare version means `cpython`. See [Preparing Environments — filtering by interpreter](guides/preparing-environments.md#filtering-by-interpreter). |
+| `--interpreter=<impl>@<version>` | For a matrixed action, restrict execution to the named interpreter(s). Repeatable; a bare version means `cpython`; `all` means the full axis, ignoring `default_interpreters`. |
 | `--resource-usage[=SEC]` | Print one `[resources]` stderr line per interval plus a peaks summary at the end (see [Resource usage in CI](#resource-usage-in-ci)). Accepted range `0 < SEC ≤ 600`; bare flag polls every 15 s. |
 | `--no-resource-usage` | Disable the reporter, including its CI default. |
 
 In a multi-project workspace, `run` fans out across every project that declares the action; spawned subprocesses are bounded by the machine-wide process budget (one slot per subprocess, leased per unit of work; default: derived from the machine's CPU budget). Fan-out is throttled, never refused — workspace size does not limit which actions you can run. See [Process budget](guides/wm-server-internals.md#process-budget).
 
-`--env` and `--interpreter` on `run` use the same selector semantics as `prepare-envs` (ADR-0050): they compose by intersection, and a matrix env's config-declared `default_interpreters` policy (see [Preparing Environments — default interpreter subset](guides/preparing-environments.md#default-interpreter-subset)) applies as the default when neither is given — so a plain `run` can execute only a local subset of a matrix (e.g. the newest interpreter) while CI still runs the full axis, mirroring `prepare-envs`. The selection also decides which interpreter instances are *started*, not only which run: unselected matrix children are never started or repaired.
+`run` selects matrix variants with `--interpreter` alone (ADR-0103): no selector applies each base's `default_interpreters` policy (see [Preparing Environments — default interpreter subset](guides/preparing-environments.md#default-interpreter-subset)) — so a plain `run` can execute only a local subset of a matrix (e.g. the newest interpreter) while CI still runs the full axis; values select exactly those interpreters; `all` selects the full axis, ignoring the policy. The selection also decides which interpreter instances are *started*, not only which run: unselected matrix children are never started or repaired.
 
 WAL environment variable and storage settings are shared with `start-wm-server` — see [`start-wm-server`](#start-wm-server) for details.
 
@@ -192,11 +191,14 @@ python -m finecode --workdir=./finecode_extension_api run lint
 # Override ruff line length
 python -m finecode run lint --config.ruff.line_length=120
 
-# Run a matrixed action's "testing" env only for its cpython@3.11 child
-python -m finecode run run_tests --env=testing@cpython-3.11
+# Run a matrixed action's 3.11 variant
+python -m finecode run run_tests --interpreter=3.11
 
 # Run every matrix env's 3.12 interpreter
 python -m finecode run run_tests --interpreter=3.12
+
+# Run the full declared axis, ignoring the default policy
+python -m finecode run run_tests --interpreter=all
 ```
 
 ---
@@ -220,7 +222,7 @@ See [Preparing Environments](guides/preparing-environments.md) for a full explan
 | Option | Description |
 |---|---|
 | `--recreate` | Delete and recreate the venvs this run covers (all, or the `--env` selection) |
-| `--env=<name>` | Restrict `create_envs` and `install_envs` to the named env(s). Repeatable. See note below. |
+| `--env=<name>` | Restrict `create_envs` and `install_envs` to the named env(s): a name, a matrix base (its default interpreters), `<base>@<impl>-<version>`, or `<base>@all`. Repeatable. See note below. |
 | `--project=<name>` | Restrict preparation to the named project(s) (matched by `[project].name` from `pyproject.toml`). Repeatable. |
 | `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 | `--verbose` / `-v` | Stream WM and ER diagnostic logs to stderr live over the protocol (`server/logRecords`). Auto-enabled in CI. |

docs/guides/developing-finecode.md

@@ -195,8 +195,8 @@ python -m finecode run --shared-server inspect_code --target=files \
 `--interpreter=3.13` restricts a matrixed `testing` run to that interpreter.
 Dropping `--interpreter` does **not** widen to the whole axis: it runs the env's
 `default_interpreters` policy, which for `testing` selects the newest
-downloadable interpreter only. To run more, pass `--dev-env=ci` (the full
-axis) or repeat `--interpreter=` for each one.
+downloadable interpreter only. To run more, pass `--interpreter=all` (the full
+axis), `--dev-env=ci`, or repeat `--interpreter=` for each one.
 
 Payload fields are validated at the CLI against the action's schema before anything
 runs: an unknown field name is refused, and a value that cannot be the field's declared

docs/guides/preparing-environments.md

@@ -259,8 +259,8 @@ This is the only command most users need. It:
 1. Discovers all projects in the workspace
 2. Bootstraps `dev_workspace` for each subproject (`create_envs` + `install_envs`, using workspace root config)
 3. Starts Extension Runners
-4. Runs `create_envs` across all projects (only the selected envs when `--env`/`--interpreter` narrows the run — see Filtering by environment name)
-5. Runs `install_envs` across all projects (only the selected envs when `--env`/`--interpreter` narrows the run — see Filtering by environment name)
+4. Runs `create_envs` across all projects (only the selected envs when `--env` narrows the run — see Filtering by environment name)
+5. Runs `install_envs` across all projects (only the selected envs when `--env` narrows the run — see Filtering by environment name)
 
 See [CLI reference — prepare-envs](../cli.md#prepare-envs) for available options.
 
@@ -349,34 +349,33 @@ Useful when you've added a new handler in one env and want to update only that e
 
 #### Matrix environments
 
-For a matrix environment (ADR-0047 — one declaring an `interpreters` axis), the same rule applies, with base-name expansion: naming a concrete matrix child — or its base name, which expands to all of its children — restricts **both** `create_envs` and `install_envs` to the selected children (PRD-0003 AC8). Unselected children of that matrix are not created at all, since there is no point creating a venv for an interpreter nobody asked for in this run.
+For a matrix base (ADR-0047 — one declaring an `interpreters` axis), `--env` takes four forms (ADR-0103). With any `--env` given, a base not named in any form contributes nothing; with no `--env`, every base contributes its default and every non-matrix env is included:
+
+| Form | Selects |
+|---|---|
+| `<base>` | that base's default interpreters |
+| `<base>@<impl>-<version>` | that one child |
+| `<base>@all` | every child |
+| `<non-matrix>` | that env |
+
+The selection restricts **both** `create_envs` and `install_envs` (PRD-0003 AC8). Unselected children are not created at all. Each base's policy selects its own children only.
 
 ```bash
-# Select every child of the "testing" matrix env.
+# The "testing" base's default subset.
 python -m finecode prepare-envs --env=testing
 
+# Every child of "testing".
+python -m finecode prepare-envs --env=testing@all
+
 # Select only the cpython@3.11 child.
 python -m finecode prepare-envs --env=testing@cpython-3.11
 ```
 
-A matrix base named by `--env` is always expanded to *all* of its children, ignoring that base's own `default_interpreters` policy (see below) — `--env` is more specific than a config default. A sibling matrix base *not* named by `--env` is unaffected by this and keeps applying its own config default (or its full axis, if it has none).
-
-### Filtering by interpreter
-
-```bash
-python -m finecode prepare-envs --interpreter=3.11
-python -m finecode prepare-envs --interpreter=pypy@3.11
-```
-
-Restricts every matrix environment's interpreter axis to the named interpreter(s), the same way for both `create_envs` and `install_envs`. `--interpreter` is repeatable to select more than one interpreter. Values may be the canonical `<impl>@<version>` form or a bare version, which is shorthand for `cpython@<version>`.
-
-`--interpreter` can be combined with `--env`: the effective selection is the intersection of the two — e.g. `--env=testing --interpreter=3.12` selects only `testing`'s `cpython@3.12` child. An `--interpreter` value that doesn't exist in a given matrix env's axis simply contributes nothing for that env (it is not an error by itself — see below for when a selector *is* rejected).
-
-Non-matrix envs are unaffected by `--interpreter`; they are created and installed unless an `--env` filter excludes them.
+`prepare-envs` has no `--interpreter`; name the child, or use `<base>@all`.
 
 ### Default interpreter subset
 
-A matrix environment can declare a default interpreter subset per dev-env, so that a plain `prepare-envs` run (no `--env`/`--interpreter`) still narrows the axis automatically:
+A matrix base can declare a default interpreter subset per dev-env, so that a plain `prepare-envs` run (no `--env`) still narrows the axis automatically:
 
 ```toml
 [tool.finecode.env.testing]
@@ -395,11 +394,11 @@ Each key is either an exact dev-env (`ide`/`cli`/`ai`/`git_hook`/`ci`) or one of
 
 Lookup for the active dev-env `D` (see [dev environment detection](../cli.md#dev-environment-detection) — `ide`/`cli`/`ai`/`git_hook`/`ci`) tries, in order: the exact key `D`, then the bucket key (`"ci"` if `D == "ci"`, otherwise `"local"`), then falls back to `"all"`. In the example above, `local = "newest"` covers `ide`/`cli`/`ai`/`git_hook`, while `ci = "all"` covers `ci` — a common pattern where local development only needs the newest interpreter, but CI verifies every interpreter in the matrix.
 
-An explicit `--interpreter` selector always overrides the config default outright, for every matrix base. A config default (or its explicit-list policy) that names an interpreter outside the env's declared axis is rejected at resolution time with a clear error.
+An explicit `--env` selector always overrides the config default outright, for its own base; each base's policy selects its own children only. A config default (or its explicit-list policy) that names an interpreter outside the env's declared axis is rejected at resolution time with a clear error.
 
-### `run` uses the same selection
+### `run` selects by interpreter
 
-`python -m finecode run` accepts the same `--env`/`--interpreter` selectors, with identical semantics (ADR-0050), to restrict which interpreter variants of a matrixed action actually execute — see [CLI reference — `run`](../cli.md#run). The config-declared `default_interpreters` policy applies there too: a plain `run` (no selectors) executes only the dev-env's default subset of a matrix (e.g. just the newest interpreter locally), while `ci` runs the full axis by default, exactly mirroring `prepare-envs`. Selection is resolved once per project (via `env_selection.resolve_selected_interpreters`) and passed down to whichever fan-out site handles the request — `matrix_runner` (non-streaming) or `matrix_streaming` (CLI / IDE streaming) — so both paths filter identically.
+`python -m finecode run` selects with `--interpreter` (ADR-0103) to restrict which interpreter variants of a matrixed action actually execute — see [CLI reference — `run`](../cli.md#run). Values select exactly those interpreters, `all` selects the full axis, and no selector applies the `default_interpreters` policy. The config-declared `default_interpreters` policy applies there too: a plain `run` (no selectors) executes only the dev-env's default subset of a matrix (e.g. just the newest interpreter locally), while `ci` runs the full axis by default. Selection is resolved once per project (via `env_selection.resolve_run_selection` into selected concrete envs) and passed down to whichever fan-out site handles the request — `matrix_runner` (non-streaming) or `matrix_streaming` (CLI / IDE streaming) via `matrix_runner.selected_variants` — so both paths filter identically.
 
 ---
 

docs/guides/wm-server-internals.md

@@ -165,19 +165,19 @@ Non-matrix actions use the existing single/multi-env dispatch path unchanged
 on both paths.
 
 A matrixed action's fan-out can be restricted to a subset of its declared
-interpreter axis (PRD-0003 AC8): `run`'s `--env`/`--interpreter` selectors
-(and, absent those, a matrix env's config-declared `default_interpreters`
+interpreter axis (ADR-0103): `run`'s `--interpreter` selectors
+(and, absent those, each base's config-declared `default_interpreters`
 policy) are resolved ONCE per project by
-`run_service/run_selection.selected_interpreters_for_project` (a thin
-WM-side wrapper around the pure `config/env_selection.resolve_selected_interpreters`
-resolver — the same resolver `prepare_envs_service` uses for `prepare-envs`)
+`run_service/run_selection.selected_envs_for_project` (a thin
+WM-side wrapper around the pure `config/env_selection.resolve_run_selection`
+resolver into selected concrete envs)
 at each run entry point (`actions/run`, `actions/runBatch`, both with and
 without a `partialResultToken`), then threaded down as a
-`selected_interpreters: set[str] | None` argument to whichever fan-out site
+`selected_envs: set[str] | None` argument to whichever fan-out site
 handles the request — `matrix_runner.run_matrix_action` or
-`matrix_streaming.run_matrix_with_partial_results`. `None` (no selectors, no
-narrowing config default) runs the full axis, unchanged; an interpreter
-outside the resolved axis raises `ActionRunFailed`.
+`matrix_streaming.run_matrix_with_partial_results` — which derive variants
+via `matrix_runner.selected_variants`. `None` (no selectors, every base full)
+runs the full axis, unchanged.
 
 ### `runner/` — ER process lifecycle and JSON-RPC client
 

docs/wm-protocol.md

@@ -433,7 +433,7 @@ converted before dispatch; MCP leaves it off so listing tools never starts
 environments.
 
 `runOptions` (optional, honoured only with `startRunners`): the selection
-inputs the run itself will use — `devEnv`, `envSelectors` and
+inputs the run itself will use — `devEnv` and
 `interpreterSelectors` (same shapes as the `actions/runBatch` run options).
 The fetch computes the same per-project interpreter selection as the run, so
 it starts only the interpreter instances the run will select. Selectors are

src/finecode/cli_app/cli.py

@@ -391,7 +391,6 @@ def run(ctx) -> None:
     dev_env: str = detect_dev_env()
     wal_enabled: bool | None = None
     verbose: bool = False
-    env_selectors: list[str] = []
     interpreter_selectors: list[str] = []
     resource_usage_flag_value: str | float | None = None
     no_resource_usage: bool = False
@@ -455,8 +454,12 @@ def run(ctx) -> None:
                     err=True,
                 )
                 sys.exit(1)
-        elif arg.startswith("--env="):
-            env_selectors.append(arg.removeprefix("--env="))
+        elif arg == "--env" or arg.startswith("--env="):
+            click.echo(
+                "run selects matrix variants by interpreter: use --interpreter=<impl>@<version> (repeatable) or --interpreter=all. --env is a prepare-envs option (ADR-0103).",
+                err=True,
+            )
+            sys.exit(1)
         elif arg.startswith("--interpreter="):
             interpreter_selectors.append(arg.removeprefix("--interpreter="))
         elif arg == "--resource-usage":
@@ -587,7 +590,6 @@ def run(ctx) -> None:
                 dev_env=dev_env,
                 wal_enabled=wal_enabled,
                 verbose=verbose,
-                env_selectors=env_selectors,
                 interpreter_selectors=interpreter_selectors,
                 resource_usage_interval=resource_usage_interval,
             )
@@ -704,14 +706,7 @@ def run(ctx) -> None:
     "env_names",
     multiple=True,
     metavar="ENV_NAME",
-    help="Limit to specific environment(s). Can be specified multiple times.",
-)
-@click.option(
-    "--interpreter",
-    "interpreter_names",
-    multiple=True,
-    metavar="IMPL@VERSION",
-    help="Limit to specific interpreter(s) of matrix environments. Repeatable; version-only form means cpython.",
+    help="Limit to specific environment(s): a name, a matrix base (its default interpreters), <base>@<impl>-<version>, or <base>@all. Repeatable.",
 )
 @click.option(
     "--project",
@@ -750,7 +745,6 @@ def prepare_envs(
     dev_env: str | None,
     workspace_packages_mode: str | None,
     env_names: tuple[str, ...],
-    interpreter_names: tuple[str, ...],
     project_names: tuple[str, ...],
     verbose: bool,
     resource_usage: float | None,
@@ -806,9 +800,6 @@ def prepare_envs(
                 own_server=not shared_server,
                 log_level=log_level,
                 env_names=list(env_names) if env_names else None,
-                interpreter_names=list(interpreter_names)
-                if interpreter_names
-                else None,
                 project_names=list(project_names) if project_names else None,
                 dev_env=dev_env or detect_dev_env(),
                 workspace_packages_mode=workspace_packages_mode,