Add --env/--interpreter selectors and matrix-keyed fan-out for interpreter-matrix actions (PRD-0003 AC8)

- env_selection.py: pure resolution of --env/--interpreter selectors plus
  each matrix env's default_interpreters policy into a concrete env subset,
  shared by prepare-envs and run.
- prepare_envs_service: create_envs skips unselected matrix children,
  install_envs installs only the selected set; --env/--interpreter and
  per-env default_interpreters policy wired through the CLI and API.
- matrix_runner.py/matrix_streaming.py/merge_helpers.py: WM-side per-
  interpreter-variant fan-out and result/streaming combination for
  matrixed actions, restricted by the resolved selection (run_selection.py).
- fine_envs/fine_python_uv: CreateEnvsAction accepts env_names filtering
  and passes the matrix env's interpreter through to `uv venv --python`.
- Add IWorkspaceActionRegistry (finecode/listWorkspaceActions) and extend
  resolveActionMeta with file locations for actions and handlers.
- Adapt PyreflyLspService and TypeCheckPythonFilesAction to resolve
  imports against the "dev" env (falling back to "runtime"), and quiet
  LintInspectCodeBridgeHandler's "no matching project" warning for
  system-triggered calls.

Author: Aksem

docs/cli.md

@@ -61,6 +61,10 @@ python -m finecode run [options] <action> [<action> ...] [payload] [--config.<ke
 | `--no-env-config` | Ignore `FINECODE_CONFIG_*` environment variables |
 | `--no-save-results` | Do not write action results to the cache directory |
 | `--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). |
+
+`--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`.
 
 WAL environment variable and storage settings are shared with `start-wm-server` — see [`start-wm-server`](#start-wm-server) for details.
 
@@ -111,6 +115,12 @@ 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 every matrix env's 3.12 interpreter
+python -m finecode run run_tests --interpreter=3.12
 ```
 
 ---

docs/wm-er-protocol.md

@@ -242,18 +242,21 @@ protocol even though the runner never became reachable. (Regression-tested in
 
 - `finecodeRunner/resolveActionMeta`
   - Params: `{}` (no params)
-  - Result: complete map of `{ "<configSource>": { "canonical_source": string, "runs_concurrently": bool, "scope": string, "parentActionSource": string | null, "language": string | null }, ... }` for every
-    action whose class can be imported in this env.  Actions that fail to import are
-    omitted entirely.
-    Example: `{ "myext.LintAction": { "canonical_source": "myext.actions.lint.LintAction", "runs_concurrently": true, "scope": "project", "parentActionSource": null, "language": null } }`
+  - Result: `{ "actions": { "<configSource>": { "canonical_source": string, "runs_concurrently": bool, "scope": string, "parentActionSource": string | null, "language": string | null, "fileLoc": string | null }, ... }, "handlerLocations": { "<handlerSource>": string | null, ... } }`.
+    `actions` covers every action whose class can be imported in this env; actions
+    that fail to import are omitted entirely. `handlerLocations` covers every handler
+    registered in this env. `fileLoc` is `"<path>:<lineno>"` of the class's source
+    (relative to the project dir when inside it, else absolute), or `null` when it
+    could not be resolved (e.g. a dynamically built class).
+    Example: `{ "actions": { "myext.LintAction": { "canonical_source": "myext.actions.lint.LintAction", "runs_concurrently": true, "scope": "project", "parentActionSource": null, "language": null, "fileLoc": "myext/actions/lint.py:10" } }, "handlerLocations": { "myext.LintHandler": "myext/lint_handler.py:20" } }`
   - Called by the WM after `finecodeRunner/updateConfig` completes to store all action
-    metadata on its `Action` domain objects before the runner is considered ready.  The
-    WM uses `canonical_source` as the primary identifier in all subsequent action
-    lookups.  `parentActionSource` and `language` are used to serve
-    `finecode/getActionsForParent` requests (see ER→WM section).  Fields absent
-    from the response (import failure) remain `None` until another runner for the same
-    project resolves them; if still unresolved when requested, resolution is retried
-    on demand (see `finecode/getActionsForParent` below).
+    and handler metadata on its `Action`/`ActionHandler` domain objects before the
+    runner is considered ready.  The WM uses `canonical_source` as the primary
+    identifier in all subsequent action lookups.  `parentActionSource` and `language`
+    are used to serve `finecode/getActionsForParent` requests (see ER→WM section).
+    Fields absent from the response (import failure) remain `None` until another
+    runner for the same project resolves them; if still unresolved when requested,
+    resolution is retried on demand (see `finecode/getActionsForParent` below).
 
 - `actions/resolveSource`
   - Params: `{ "source": string }` — an arbitrary import-path alias to resolve.

extensions/fine_python_lang/fine_python_lang/type_check_python_files_action.py

@@ -14,7 +14,27 @@ class TypeCheckPythonFilesAction(
         DiagnosticFilesRunResult,
     ]
 ):
-    """Type-check Python source files and report type errors."""
+    """Type-check Python source files and report type errors.
+
+    Handler recommendation — env for import resolution:
+    A type checker needs one environment to resolve the imports of the code it
+    checks. Test files often pull in dev-only dependencies (e.g. pytest) that are
+    absent from the "runtime" env, so resolving everything against "runtime" makes
+    those imports unresolvable. Handlers should therefore resolve imports against
+    the "dev" env (a superset of "runtime": project deps + dev-only deps), falling
+    back to "runtime" when no "dev" env exists. Falling back only loses symbols,
+    never adds false ones.
+
+    The trade-off is that dev-only deps then resolve from source files too, so the
+    type checker no longer flags a dev dependency imported from source. That
+    boundary is intentionally delegated to a dependency-hygiene tool (e.g. deptry),
+    which must be wired into the same gate so the boundary is still enforced.
+
+    Note: "dev"/"runtime" are naming conventions — env labels are arbitrary — so
+    this env selection could be made configurable in the future, either per handler
+    or at the action level (one resolution-env policy shared by all of the action's
+    handlers).
+    """
 
     DESCRIPTION = "Type-check Python source files and report type errors."
     PAYLOAD_TYPE = DiagnosticFilesRunPayload

extensions/fine_python_pyrefly/fine_python_pyrefly/pyrefly_lsp_service.py

@@ -78,11 +78,32 @@ def __init__(
             client_capabilities=_PYREFLY_CLIENT_CAPABILITIES,
         )
         # pyrefly's own environment/interpreter auto-detection does not know about
-        # FineCode's per-project "runtime" env, so without this it resolves imports
-        # against the wrong (or no) site-packages. Applied here so every feature
-        # (hover, definition, inlay hints, ...) gets it, not just type checking.
+        # FineCode's per-project envs, so without this it resolves imports against the
+        # wrong (or no) site-packages. Applied here so every feature (hover, definition,
+        # inlay hints, ...) gets it, not just type checking.
+        #
+        # A single LSP server can only be configured with one resolution env at startup
+        # (it cannot switch per file), so the broadest env is used: "dev" is a superset
+        # of "runtime" (project deps + dev-only deps such as pytest), which lets test
+        # files resolve their imports too. Falling back to "runtime" when "dev" does not
+        # exist only loses symbols, never adds false ones.
+        #
+        # Trade-off: dev-only deps become resolvable from source files too, so pyrefly no
+        # longer flags a dev dependency imported from source. That boundary is enforced
+        # separately by a dependency-hygiene tool (e.g. deptry). "dev"/"runtime" are
+        # naming conventions (env labels are arbitrary); this could be made configurable
+        # in the future, per handler or at the action level.
         self._pyrefly_settings: dict[str, Any] = {}
-        venv_dir = extension_runner_info_provider.get_venv_dir_path_of_env("runtime")
+        resolution_env = "dev"
+        venv_dir = extension_runner_info_provider.get_venv_dir_path_of_env(
+            resolution_env
+        )
+        if not venv_dir.exists():
+            resolution_env = "runtime"
+            venv_dir = extension_runner_info_provider.get_venv_dir_path_of_env(
+                resolution_env
+            )
+        logger.debug(f"pyrefly resolves imports against the '{resolution_env}' env")
         interpreter_path = extension_runner_info_provider.get_venv_python_interpreter(
             venv_dir
         )

extensions/fine_python_uv/src/fine_python_uv/create_env_handler.py

@@ -38,6 +38,12 @@ def __init__(
     async def _is_valid_virtualenv(self, venv_dir_path: Path) -> bool:
         # A valid venv must contain pyvenv.cfg and a runnable interpreter that
         # reports a virtualenv prefix relationship.
+        #
+        # NOTE: this probe does not check that the
+        # existing venv's interpreter actually matches `env_info.interpreter`. It could
+        # be extended to probe the venv python's `platform.python_implementation()` +
+        # version and treat a mismatch as invalid, so that changing an env's
+        # interpreter rebuilds a now-stale venv instead of silently keeping the old one.
         pyvenv_cfg = venv_dir_path / "pyvenv.cfg"
         if not pyvenv_cfg.exists():
             return False
@@ -93,7 +99,10 @@ async def run(
 
             uv_executable = get_uv_executable()
             # venv can exist but be invalid, use '--clear' to recreate it
-            cmd = f'"{uv_executable}" venv --clear "{venv_dir_path}"'
+            python_flag = (
+                f' --python "{env_info.interpreter}"' if env_info.interpreter else ""
+            )
+            cmd = f'"{uv_executable}" venv --clear{python_flag} "{venv_dir_path}"'
             self.logger.debug(f"Running uv: {cmd}")
             process = await self.command_runner.run(cmd, cwd=dump_dir)
             await process.wait_for_end()

extensions/fine_python_uv/tests/__init__.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import pathlib
+from typing import Any
+
+from fine_envs import create_env_action, create_envs_action
+from finecode_extension_api.interfaces import (
+    icommandrunner,
+    ifilemanager,
+    ilogger,
+    iprojectactionrunner,
+    iprojectinfoprovider,
+)
+from finecode_extension_api.resource_uri import path_to_resource_uri
+from finecode_extension_runner.testing import NoOpLogger, run_handler
+
+from fine_python_uv.create_env_handler import UvCreateEnvHandler
+
+
+class _FakeProcess:
+    def get_exit_code(self) -> int | None:
+        return 0
+
+    def get_output(self) -> str:
+        return ""
+
+    def get_error_output(self) -> str:
+        return ""
+
+    def write_to_stdin(self, value: str) -> None:
+        pass
+
+    def close_stdin(self) -> None:
+        pass
+
+    async def wait_for_end(self, timeout: float | None = None) -> None:
+        pass
+
+
+class _FakeCommandRunner:
+    """Captures every command string it is asked to run, instead of executing it."""
+
+    def __init__(self) -> None:
+        self.commands: list[str] = []
+
+    async def run(
+        self,
+        cmd: str,
+        cwd: pathlib.Path | None = None,
+        env: dict[str, str] | None = None,
+    ) -> _FakeProcess:
+        self.commands.append(cmd)
+        return _FakeProcess()
+
+    def run_sync(
+        self,
+        cmd: str,
+        cwd: pathlib.Path | None = None,
+        env: dict[str, str] | None = None,
+    ) -> _FakeProcess:
+        raise NotImplementedError
+
+
+class _FakeFileManager:
+    async def get_content(self, file_path: pathlib.Path) -> str:
+        raise NotImplementedError
+
+    async def get_file_version(self, file_path: pathlib.Path) -> str:
+        raise NotImplementedError
+
+    async def save_file(self, file_path: pathlib.Path, file_content: str) -> None:
+        pass
+
+    async def create_dir(
+        self, dir_path: pathlib.Path, create_parents: bool = True, exist_ok: bool = True
+    ) -> None:
+        pass
+
+    async def remove_dir(self, dir_path: pathlib.Path) -> None:
+        pass
+
+
+class _FakeProjectActionRunner:
+    """No-ops `run_action` so the handler's config-dump step doesn't need a real
+    DumpConfigAction handler registered in the test session."""
+
+    async def get_actions_for_parent(self, parent_action_type: type) -> dict[str, Any]:
+        raise NotImplementedError
+
+    async def run_action(
+        self,
+        action_type: Any,
+        payload: Any,
+        meta: Any,
+        caller_kwargs: Any = None,
+    ) -> None:
+        return None
+
+    def run_action_iter(
+        self,
+        action_type: Any,
+        payload: Any,
+        meta: Any,
+        caller_kwargs: Any = None,
+    ) -> Any:
+        raise NotImplementedError
+
+
+class _FakeProjectInfoProvider:
+    """Only `get_project_raw_config` is exercised (by the config-dump step)."""
+
+    def get_current_project_dir_path(self) -> pathlib.Path:
+        raise NotImplementedError
+
+    def get_current_project_def_path(self) -> pathlib.Path:
+        raise NotImplementedError
+
+    async def get_current_project_package_name(self) -> str:
+        raise NotImplementedError
+
+    async def get_project_raw_config(self, project_def_path: pathlib.Path) -> dict[str, Any]:
+        return {}
+
+    async def get_current_project_raw_config(self) -> dict[str, Any]:
+        raise NotImplementedError
+
+    def get_current_project_raw_config_version(self) -> int:
+        raise NotImplementedError
+
+    async def get_workspace_editable_packages(self) -> dict[str, pathlib.Path]:
+        raise NotImplementedError
+
+
+def _service_overrides(command_runner: _FakeCommandRunner) -> dict[type, Any]:
+    return {
+        icommandrunner.ICommandRunner: command_runner,
+        ilogger.ILogger: NoOpLogger(),
+        ifilemanager.IFileManager: _FakeFileManager(),
+        iprojectactionrunner.IProjectActionRunner: _FakeProjectActionRunner(),
+        iprojectinfoprovider.IProjectInfoProvider: _FakeProjectInfoProvider(),
+    }
+
+
+async def test_uv_venv_command_includes_python_flag_when_interpreter_is_set(
+    tmp_path: pathlib.Path,
+) -> None:
+    command_runner = _FakeCommandRunner()
+    # venv_dir_path must not exist so `_is_valid_virtualenv` returns False and the
+    # create path (which builds the `uv venv` command) actually runs.
+    venv_dir_path = tmp_path / "venvs" / "testing"
+    project_def_path = tmp_path / "pyproject.toml"
+    env_info = create_envs_action.EnvInfo(
+        name="testing@cpython-3.11",
+        venv_dir_path=path_to_resource_uri(venv_dir_path),
+        project_def_path=path_to_resource_uri(project_def_path),
+        interpreter="cpython@3.11",
+    )
+    payload = create_env_action.CreateEnvRunPayload(env=env_info, recreate=False)
+
+    result = await run_handler(
+        UvCreateEnvHandler,
+        payload,
+        action_cls=create_env_action.CreateEnvAction,
+        project_dir=tmp_path,
+        service_overrides=_service_overrides(command_runner),
+    )
+
+    assert result is not None
+    assert result.errors == []
+    venv_commands = [cmd for cmd in command_runner.commands if " venv " in cmd]
+    assert len(venv_commands) == 1
+    assert '--python "cpython@3.11"' in venv_commands[0]
+
+
+async def test_uv_venv_command_omits_python_flag_when_interpreter_is_none(
+    tmp_path: pathlib.Path,
+) -> None:
+    command_runner = _FakeCommandRunner()
+    venv_dir_path = tmp_path / "venvs" / "dev"
+    project_def_path = tmp_path / "pyproject.toml"
+    env_info = create_envs_action.EnvInfo(
+        name="dev",
+        venv_dir_path=path_to_resource_uri(venv_dir_path),
+        project_def_path=path_to_resource_uri(project_def_path),
+        interpreter=None,
+    )
+    payload = create_env_action.CreateEnvRunPayload(env=env_info, recreate=False)
+
+    result = await run_handler(
+        UvCreateEnvHandler,
+        payload,
+        action_cls=create_env_action.CreateEnvAction,
+        project_dir=tmp_path,
+        service_overrides=_service_overrides(command_runner),
+    )
+
+    assert result is not None
+    assert result.errors == []
+    venv_commands = [cmd for cmd in command_runner.commands if " venv " in cmd]
+    assert len(venv_commands) == 1
+    assert "--python" not in venv_commands[0]

extensions/fine_python_uv/tests/test_create_env_handler.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import dataclasses
+import typing
+
+from finecode_extension_api import service
+
+__all__ = ["HandlerInfo", "ActionInfo", "IWorkspaceActionRegistry"]
+
+
+@dataclasses.dataclass(frozen=True)
+class HandlerInfo:
+    name: str
+    source: str
+    env: str
+    file_loc: str | None
+
+
+@dataclasses.dataclass(frozen=True)
+class ActionInfo:
+    name: str
+    source: str
+    canonical_source: str | None
+    scope: str
+    project: str
+    language: str | None
+    parent_action_source: str | None
+    file_loc: str | None
+    handlers: list[HandlerInfo]
+
+
+class IWorkspaceActionRegistry(service.Service, typing.Protocol):
+    """Read-only access to the workspace action and handler registry."""
+
+    async def list_actions(self) -> list[ActionInfo]: ...