diff --git a/docker/Dockerfile b/docker/Dockerfile
index b4e8c8b969..4b7a478b7a 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -129,6 +129,9 @@ ENV RAY_USAGE_STATS_ENABLED=0
 # There is severe contention and performance issues with this enabled considering our dependencies are so large and occasionally
 # need to be compiled, so NeMo RL has an implementation in nemo_rl/utils/venv.py that does it once per node as opposed to once per task.
 ENV RAY_ENABLE_UV_RUN_RUNTIME_ENV=0
+# Set once here: `hermetic` and `release` both derive from `base`, so they inherit it.
+# The worker-venv prefetch in the hermetic stage reads it -- do not re-declare it in a
+# later stage, or the value the prefetch uses and the value the image ships can drift.
 ENV NEMO_RL_VENV_DIR=/opt/ray_venvs
 ENV NEMO_GYM_VENV_DIR=/opt/gym_venvs
 
@@ -197,6 +200,10 @@ ENV LD_LIBRARY_PATH="/opt/nemo_rl_venv/lib/python3.13/site-packages/z3/lib:/opt/
 COPY --from=nemo-rl pyproject.toml uv.lock ./
 # Copy in the top level __init__.py/package_info.py since build-custom-vllm.sh needs the nemo_rl package to exist.
 COPY --from=nemo-rl nemo_rl/__init__.py nemo_rl/package_info.py ./nemo_rl/
+# The single source of truth for which extras each Ray actor's venv needs. Run as a
+# script by the prefetch below; imported by nemo_rl.distributed.ray_actor_environment_registry
+# at runtime. Kept dependency-free so it can be copied in without the rest of the source.
+COPY --from=nemo-rl nemo_rl/distributed/actor_environments.py ./nemo_rl/distributed/
 COPY --from=nemo-rl tools/build-custom-vllm.sh ./tools/build-custom-vllm.sh
 COPY --from=nemo-rl tools/build-custom-flashinfer.sh ./tools/build-custom-flashinfer.sh
 COPY --from=nemo-rl --link research/ ./research/
@@ -234,7 +241,7 @@ fi
 # to warm the uv cache, then at the end just sync the default dependencies.
 # Do everything in one layer to prevent large layers.
 
-# The venv is symlinked to avoid bloating the layer size
+# Everything is hardlinked against the uv cache; this layer holds exactly one real copy of every wheel.
 UV_LINK_MODE=hardlink uv sync --frozen --no-install-project
 if [[ -z "${SKIP_VLLM_BUILD:-}" ]]; then
     UV_LINK_MODE=hardlink uv sync --frozen --extra vllm --no-install-project
@@ -242,10 +249,57 @@ fi
 if [[ -z "${SKIP_SGLANG_BUILD:-}" ]]; then
     UV_LINK_MODE=hardlink uv sync --frozen --extra sglang --no-install-project
 fi
-uv sync --link-mode symlink --frozen --extra mcore --no-install-project
-uv sync --link-mode symlink --frozen --extra automodel --no-install-project
-uv sync --link-mode symlink --frozen --extra modelopt --no-install-project
-uv sync --link-mode symlink --frozen --all-groups --no-install-project
+UV_LINK_MODE=hardlink uv sync --frozen --extra mcore --no-install-project
+UV_LINK_MODE=hardlink uv sync --frozen --extra automodel --no-install-project
+UV_LINK_MODE=hardlink uv sync --frozen --extra modelopt --no-install-project
+UV_LINK_MODE=hardlink uv sync --frozen --all-groups --no-install-project
+
+# Worker-venv prefetch, phase 1: third-party packages only.
+#
+# Each Ray actor runs in its own venv under NEMO_RL_VENV_DIR. Build them HERE, in the same
+# layer as the uv cache above, because a hardlink into an already-finished layer makes
+# overlayfs copy the file up -- so building them later would trade ~1.5M symlinks for
+# gigabytes of duplicated wheels. Built here, the N venvs cost directory entries and share
+# one copy of every wheel with the cache.
+#
+# Why not just run nemo_rl/utils/prefetch_venvs.py, which already knows how to build these?
+# Because it installs the nemo_rl project into each venv, and the source tree does not exist
+# yet -- this layer has only pyproject.toml, uv.lock and a couple of standalone files (see
+# the COPY above). The source arrives much later, in the release stage, deliberately: copying
+# it earlier would make every source edit invalidate this hour-long dependency build.
+# So the work is split. Here we do the expensive, cacheable half: every third-party package,
+# hardlinked, with --no-install-project so nemo_rl itself is left out. prefetch_venvs.py then
+# runs in the release stage and does the cheap half -- the editable nemo_rl install (a .pth
+# file) plus the python-<ClassName> wrapper scripts. Same venvs, finished in two places.
+#
+# nemo_rl/distributed/actor_environments.py is the single source of truth for which extras
+# each actor needs; the runtime registry imports the same dict. It is run as a script rather
+# than imported, because importing it would execute nemo_rl/__init__.py, which does real work
+# (fingerprint check, sys.path setup) that cannot run in this layer.
+SKIP_EXTRAS=""
+if [[ -n "${SKIP_VLLM_BUILD:-}" ]]; then
+    SKIP_EXTRAS="$SKIP_EXTRAS vllm"
+fi
+if [[ -n "${SKIP_SGLANG_BUILD:-}" ]]; then
+    SKIP_EXTRAS="$SKIP_EXTRAS sglang"
+fi
+if [[ -n "${SKIP_TRTLLM_BUILD:-}" ]]; then
+    SKIP_EXTRAS="$SKIP_EXTRAS trtllm"
+fi
+# Write the list once, in a plain redirect so `set -e` catches a failure here
+# instead of silently prefetching nothing.
+"${UV_PROJECT_ENVIRONMENT}/bin/python" nemo_rl/distributed/actor_environments.py all $SKIP_EXTRAS \
+    > /opt/actor_venvs.tsv
+test -s /opt/actor_venvs.tsv
+while IFS=$'\t' read -r venv_name stage extras; do
+    if [[ "$stage" == "trtllm" ]]; then
+        # tensorrt_llm does not exist yet; warm the base and finish in the TRT-LLM layer.
+        extras=""
+    fi
+    venv_path="${NEMO_RL_VENV_DIR}/${venv_name}"
+    uv venv --allow-existing "$venv_path"
+    UV_PROJECT_ENVIRONMENT="$venv_path" UV_LINK_MODE=hardlink uv sync --frozen $extras --no-install-project
+done < /opt/actor_venvs.tsv
 
 # Remove the aiohttp in this uv cache dir to fully address CVE GHSA-mqqc-3gqh-h2x8
 # The ray install will include the older aiohttp version in its cache
@@ -298,8 +352,14 @@ du -sh /root/.cache/uv /root/.cache/trtllm-wheels
 
 TRTLLM_SYNC_LOG=$(mktemp /tmp/trtllm-sync.XXXXXX.log)
 set +e
+# Build TRT-LLM into a throwaway venv instead of the main one:
+# the main venv is fully hardlinked from the dependency layer,
+# and churning it here would copy files up into this layer.
+# The throwaway venv must be symlink-mode: hardlinks to files in the dependency layer's uv
+# cache make overlayfs copy them up into this layer, and the copies outlive the rm -rf below.
 UV_CACHE_DIR=/root/.cache/uv \
     TRTLLM_WHEEL_CACHE_DIR=/root/.cache/trtllm-wheels \
+    UV_PROJECT_ENVIRONMENT=/tmp/trtllm-build-venv \
     uv sync --verbose --link-mode symlink --locked --extra trtllm --no-install-project \
     2>&1 | tee "$TRTLLM_SYNC_LOG" \
     | awk '/\[TRTLLM_CCACHE\]|Ninja progress:/ { print; fflush() }'
@@ -317,17 +377,35 @@ rm -f "$TRTLLM_SYNC_LOG"
 echo "TRT-LLM cache state after build:"
 du -sh /root/.cache/uv /root/.cache/trtllm-wheels
 
-# Restore the intended default environment in the same layer so the transient
-# TRT-LLM installation does not add a large intermediate venv layer.
-uv sync --link-mode symlink --locked --all-groups --no-install-project
-
-# The final sync can repopulate the shared uv cache, so repeat the security
+# Worker-venv prefetch, phase 1 for the "trtllm"-stage actors:
+# the dependency layer gave them a base-only warm; now that the tensorrt_llm wheel exists,
+# top off the venv with the full extra set so that the added files hardlink in-layer.
+# tensorrt_llm itself is new in this layer; trtllm-extra deps already present in the
+# dependency layer's cache (e.g. tilelang) get copied up here, a small accepted cost.
+# The dependency layer already wrote the actor list to /opt/actor_venvs.tsv, so this layer
+# reuses it rather than re-deriving it -- one reader, one place it can go wrong.
+while IFS=$'\t' read -r venv_name stage extras; do
+    if [[ "$stage" != "trtllm" ]]; then
+        continue
+    fi
+    venv_path="${NEMO_RL_VENV_DIR}/${venv_name}"
+    uv venv --allow-existing "$venv_path"
+    UV_PROJECT_ENVIRONMENT="$venv_path" UV_LINK_MODE=hardlink \
+        TRTLLM_WHEEL_CACHE_DIR=/root/.cache/trtllm-wheels \
+        TRTLLM_REQUIRE_CACHED_WHEEL=1 \
+        uv sync --frozen $extras --no-install-project
+done < /opt/actor_venvs.tsv
+
+# The main venv was never touched (the build ran in the throwaway venv), so
+# the previous "restore the default environment" sync is no longer needed.
+rm -rf /tmp/trtllm-build-venv
+
+# The syncs above can repopulate the shared uv cache, so repeat the security
 # cleanup performed in the preceding dependency layer.
 find /root/.cache/uv -type d -path "*ray/_private/runtime_env/agent/thirdparty_files/aiohttp*" -exec rm -rf {} +
 EOF
 
 ENV PATH="/opt/nemo_rl_venv/bin:$PATH"
-ENV NEMO_RL_VENV_DIR=/opt/ray_venvs
 
 # Custom setup layer (override with: --build-context custom-setup=<dir> --build-arg CUSTOM_SETUP_FNAME=<script>)
 # To skip: --build-arg CUSTOM_SETUP_FNAME=
@@ -346,9 +424,6 @@ WORKDIR /opt/nemo-rl
 FROM hermetic AS release
 
 # Re-declare build args for this stage
-ARG SKIP_VLLM_BUILD
-ARG SKIP_SGLANG_BUILD
-ARG SKIP_TRTLLM_BUILD
 ARG BUILD_DYNAMO
 ARG DYNAMO_PYTHON_VERSION=3.12.11
 ARG ETCD_VERSION=v3.5.21
@@ -367,7 +442,6 @@ ENV NVIDIA_BUILD_REF=${NVIDIA_BUILD_REF:-<unknown>}
 LABEL com.nvidia.build.id="${NVIDIA_BUILD_ID}"
 LABEL com.nvidia.build.ref="${NVIDIA_BUILD_REF}"
 
-ENV NEMO_RL_VENV_DIR=/opt/ray_venvs
 ENV NEMO_RL_DYNAMO_VENV_DIR=/opt/dynamo_venv
 
 # AWS EFA OFI plugin discovery (p4d / p5 / p5en multi-node NCCL via SRD).
@@ -400,16 +474,6 @@ EOF
 RUN git rev-parse --is-shallow-repository | grep -q true && git fetch --unshallow || true
 ARG BASE_IMAGE
 RUN --mount=type=cache,id=trtllm-wheel-cache-${TARGETARCH}-${BASE_IMAGE},from=trtllm-wheel-cache-seed,source=.,target=/root/.cache/trtllm-wheels,sharing=locked <<"EOF" bash -exu
-NEGATIVE_FILTERS=""
-if [[ -n "${SKIP_VLLM_BUILD:-}" ]]; then
-    NEGATIVE_FILTERS="$NEGATIVE_FILTERS vllm"
-fi
-if [[ -n "${SKIP_SGLANG_BUILD:-}" ]]; then
-    NEGATIVE_FILTERS="$NEGATIVE_FILTERS sglang"
-fi
-if [[ -n "${SKIP_TRTLLM_BUILD:-}" ]]; then
-    NEGATIVE_FILTERS="$NEGATIVE_FILTERS trtllm"
-fi
 # Reuse the custom wheel produced by the hermetic stage. Normal uv artifacts
 # stay in /root/.cache/uv, which remains available to symlinked environments.
 # Mirror only the current content-addressed TRT-LLM wheel into the image so
@@ -417,16 +481,32 @@ fi
 export TRTLLM_WHEEL_CACHE_DIR=/root/.cache/trtllm-wheels
 export TRTLLM_WHEEL_CACHE_MIRROR_DIR=/opt/trtllm_wheels
 export TRTLLM_REQUIRE_CACHED_WHEEL=1
-if [[ -n "$NEGATIVE_FILTERS" ]]; then
-    UV_LINK_MODE=symlink uv run nemo_rl/utils/prefetch_venvs.py --negative-filters $NEGATIVE_FILTERS
-else
-    UV_LINK_MODE=symlink uv run nemo_rl/utils/prefetch_venvs.py
-fi
+# Worker-venv prefetch, phase 2: the nemo_rl project itself.
+#
+# The other half of the split described in the dependency stage. Every venv already holds
+# its third-party packages, hardlinked in the layer that owns the uv cache. What was missing
+# is nemo_rl, because the source did not exist back there. It does now (COPY above), so
+# prefetch_venvs.py adds the editable install to each venv -- a .pth file, so this stays
+# cheap -- and writes the python-<ClassName> wrapper scripts into /usr/local/bin.
+#
+# This is why the venvs cannot simply be built here in one pass: hardlinking against the
+# dependency layer's cache from this layer would make overlayfs copy every wheel up.
+# Build exactly the venvs phase 1 built, by name. Re-deriving the list here would
+# mean filtering on the actor name again, which cannot tell that e.g.
+# AsyncTrajectoryCollector needs the vLLM extra -- so under SKIP_VLLM_BUILD the two
+# passes would disagree and this layer would build three venvs the dependency layer
+# deliberately skipped. prefetch_venvs.py matches these positionally as substrings,
+# and a full FQN matches only itself.
+UV_LINK_MODE=hardlink uv run nemo_rl/utils/prefetch_venvs.py $(cut -f1 /opt/actor_venvs.tsv)
 EOF
 
 # Prefetch NeMo Gym internal venvs (gym servers like code_gen, math_with_judge, etc.)
 # into the image. Gated on NEMO_GYM_PREFETCH_CONFIGS (no-op by default). Runs after the
 # source COPY above so examples/nemo_gym/prefetch_venvs.py is present.
+# UV_LINK_MODE=symlink below applies to this outer `uv run` only. The gym server venvs
+# themselves are built in hardlink mode: examples/nemo_gym/prefetch_venvs.py pins
+# UV_LINK_MODE=hardlink in the Gym actor's runtime_env, because Gym's setup scripts shell
+# out to `uv pip install --no-cache`, which uv refuses to combine with symlink installs.
 # Gym pins vllm==0.24.0; override it to vLLM's default prebuilt CUDA wheel so Gym's venvs share
 # RL's torch/nvidia stack. UV_TORCH_BACKEND keeps torch on the same CUDA backend.
 ARG NEMO_GYM_CUDA=cu130
diff --git a/docs/design-docs/dependency-management.md b/docs/design-docs/dependency-management.md
index 9cf3d9c3be..7b5d70389c 100644
--- a/docs/design-docs/dependency-management.md
+++ b/docs/design-docs/dependency-management.md
@@ -94,17 +94,23 @@ Within the driver script, NeMo RL starts multiple [`RayWorkerGroup`](https://git
 - **Generation workers** (e.g., vLLM): Require `vllm` dependencies  
 - **Environment workers** (e.g., math evaluation): Use system/base dependencies
 
-Each worker type is mapped to a specific Python executable configuration in the [`ACTOR_ENVIRONMENT_REGISTRY`](https://github.com/NVIDIA-NeMo/RL/blob/main/nemo_rl/distributed/ray_actor_environment_registry.py#L17-L55). This registry defines which virtual environment should be used for each actor type:
+Each worker type is mapped to the uv extras its virtual environment needs in `ACTOR_ENVIRONMENTS` in [`nemo_rl/distributed/actor_environments.py`](https://github.com/NVIDIA-NeMo/RL/blob/main/nemo_rl/distributed/actor_environments.py). [`ACTOR_ENVIRONMENT_REGISTRY`](https://github.com/NVIDIA-NeMo/RL/blob/main/nemo_rl/distributed/ray_actor_environment_registry.py) is built from it at import time, and `docker/Dockerfile` runs the same module as a script to prefetch one virtual environment per worker type into the image:
 
 ```python
-ACTOR_ENVIRONMENT_REGISTRY: dict[str, str] = {
-    "nemo_rl.models.generation.vllm.vllm_worker.VllmGenerationWorker": PY_EXECUTABLES.VLLM,
-    "nemo_rl.models.policy.workers.megatron_policy_worker.MegatronPolicyWorker": PY_EXECUTABLES.MCORE,
-    "nemo_rl.environments.math_environment.MathEnvironment": PY_EXECUTABLES.SYSTEM,
+# nemo_rl/distributed/actor_environments.py -- None means the driver's interpreter
+ACTOR_ENVIRONMENTS: dict[str, list[str] | None] = {
+    # An actor can need more than one extra: the vLLM workers also get nemo_gym
+    # because token capture imports it inside the worker.
+    "nemo_rl.models.generation.vllm.vllm_worker.VllmGenerationWorker": ["vllm", "nemo_gym"],
+    "nemo_rl.models.policy.workers.megatron_policy_worker.MegatronPolicyWorker": ["mcore"],
+    "nemo_rl.environments.math_environment.MathEnvironment": None,
     # ... more mappings
 }
 ```
 
+This module is deliberately dependency-free: `docker/Dockerfile` runs it as a script
+from the dependency layer, where the rest of the source tree does not exist yet.
+
 > [!NOTE]
 > For more details on how workers define and use their Python executables, see the [UV Documentation](uv.md#worker-configuration).
 
@@ -280,6 +286,10 @@ NeMo RL containers enforce environment reproducibility by automatically checking
 
 - The **md5sum of `pyproject.toml`**
 - The **md5sum of `uv.lock`**
+- The **md5sum of `nemo_rl/distributed/actor_environments.py`** (the actor → uv extras
+  table). Worker virtual environments are reused rather than rebuilt, and nothing prunes
+  them, so changing an actor's extras has to invalidate the fingerprint the same way a
+  dependency change does.
 - The **commit hashes of relevant submodules**
 
 If any of these values differ between your code and the container image, NeMo RL will alert you and show exactly what has changed:
@@ -298,6 +308,9 @@ Differences found:
   - uv.lock:
       Container: 0987f6543210
       Current:   1234abcd5678
+  - nemo_rl/distributed/actor_environments.py:
+      Container: 2b3c4d5e6f70
+      Current:   9a8b7c6d5e4f
   - submodules/3rdparty/ExampleSubmodule:
       Container: a1b2c3d4e5f6
       Current:   f6e5d4c3b2a1
diff --git a/docs/design-docs/uv.md b/docs/design-docs/uv.md
index 62b2bcb697..31baa3889a 100644
--- a/docs/design-docs/uv.md
+++ b/docs/design-docs/uv.md
@@ -40,7 +40,7 @@ This section outlines how workers define their required executables, details the
 
 ### Worker Configuration
 
-In our codebase, workers (classes decorated with `@ray.remote`, e.g., `PolicyWorker`) are associated with a `PY_EXECUTABLE` which specifies what dependencies the worker needs. These are set in a global registry in [`ACTOR_ENVIRONMENT_REGISTRY`](../../nemo_rl/distributed/ray_actor_environment_registry.py). This allows different parts of our application to have their own tailored environments.
+In our codebase, workers (classes decorated with `@ray.remote`, e.g., `PolicyWorker`) are associated with a `PY_EXECUTABLE` which specifies what dependencies the worker needs. These are declared in `ACTOR_ENVIRONMENTS` in [`nemo_rl/distributed/actor_environments.py`](../../nemo_rl/distributed/actor_environments.py), from which the global registry [`ACTOR_ENVIRONMENT_REGISTRY`](../../nemo_rl/distributed/ray_actor_environment_registry.py) is built. Workers defined outside this repo register themselves by assigning into `ACTOR_ENVIRONMENT_REGISTRY` at runtime -- see `research/template_project`. This allows different parts of our application to have their own tailored environments.
 
 ### Supported Python Executables
 
@@ -72,7 +72,7 @@ When a NeMo RL job is started:
 1. The driver script creates several {py:class}`RayWorkerGroup <nemo_rl.distributed.worker_groups.RayWorkerGroup>`s.
 2. Each worker group will create their workers which are wrapped in a {py:class}`RayWorkerBuilder <nemo_rl.distributed.worker_groups.RayWorkerBuilder>` where the fully qualified name (FQN) of the worker class is passed as a string.
 3. {py:class}`RayWorkerBuilder <nemo_rl.distributed.worker_groups.RayWorkerBuilder>` launches the worker under {py:class}`RayWorkerBuilder <nemo_rl.distributed.worker_groups.RayWorkerBuilder. IsolatedWorkerInitializer>` which allows us to initialize the class without importing packages not available in the base environment.
-4. Before the worker class is instantiated by the `RayWorkerBuilder`, the FQN is used to lookup -- in a [global registry](../../nemo_rl/distributed/ray_actor_environment_registry.py))) -- to determine which member of `PY_EXECUTABLES` should be used to launch that set of workers. If the chosen `PY_EXECUTABLES.*` starts with `uv`; a `venv` is created with all the dependencies it needs and the `runtime_env["py_executable"]` is replaced with the `venv`'s python interpreter.
+4. Before the worker class is instantiated by the `RayWorkerBuilder`, the FQN is used to lookup -- in a [global registry](../../nemo_rl/distributed/ray_actor_environment_registry.py) built from [`ACTOR_ENVIRONMENTS`](../../nemo_rl/distributed/actor_environments.py) -- to determine which member of `PY_EXECUTABLES` should be used to launch that set of workers. If the chosen `PY_EXECUTABLES.*` starts with `uv`; a `venv` is created with all the dependencies it needs and the `runtime_env["py_executable"]` is replaced with the `venv`'s python interpreter.
 
 This approach allows a fast start-up and maintains dependency isolation. It also has the added benefit of having all the virtual environments local under `./venvs`.
 
diff --git a/nemo_rl/distributed/actor_environments.py b/nemo_rl/distributed/actor_environments.py
new file mode 100644
index 0000000000..5c42e1f5c3
--- /dev/null
+++ b/nemo_rl/distributed/actor_environments.py
@@ -0,0 +1,160 @@
+# Copyright (c) 2026, NVIDIA CORPORATION.  All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Which uv extras each Ray actor needs. The single source of truth.
+
+Two readers:
+
+* ``nemo_rl.distributed.ray_actor_environment_registry`` imports
+  ``ACTOR_ENVIRONMENTS`` and turns it into ``py_executable`` strings at runtime.
+* ``docker/Dockerfile`` runs this file **as a script** to list the venvs it must
+  pre-build, so the image ships one venv per actor.
+
+DO NOT IMPORT ANYTHING FROM ``nemo_rl`` HERE, AND KEEP IT STDLIB-ONLY.
+The Dockerfile runs this from the dependency layer, where ``pyproject.toml``,
+``uv.lock`` and a handful of standalone files exist, but the rest of the
+``nemo_rl`` package does not (see the ``COPY`` directives in
+``docker/Dockerfile``). Running it as a script rather than importing it is what
+keeps ``nemo_rl/__init__.py`` -- which is copied in, and does real work at import
+-- from executing there. An import added here breaks the image build in its most
+expensive layer.
+``tests/unit/distributed/test_actor_environments.py`` enforces this.
+"""
+
+# Keeps the annotations below from being evaluated at runtime, so this module also
+# runs under interpreters older than the one the image pins.
+from __future__ import annotations
+
+import sys
+
+# Actor fully-qualified name -> the uv extras its virtual environment needs.
+# ``None`` means the actor runs on the driver's interpreter and gets no venv.
+# Every extra must exist in ``[project.optional-dependencies]`` of pyproject.toml.
+ACTOR_ENVIRONMENTS: dict[str, list[str] | None] = {
+    # vLLM workers always get vllm + nemo_gym. Token capture (token_capture.enabled)
+    # imports nemo_gym inside the worker, and worker venvs are cached by actor class
+    # name -- a venv prebuilt with plain "vllm" is reused as-is, so the extras have to
+    # be fixed here rather than swapped in at runtime.
+    "nemo_rl.models.generation.vllm.vllm_worker.VllmGenerationWorker": [
+        "vllm",
+        "nemo_gym",
+    ],
+    "nemo_rl.models.generation.vllm.vllm_worker_async.VllmAsyncGenerationWorker": [
+        "vllm",
+        "nemo_gym",
+    ],
+    "nemo_rl.models.generation.sglang.sglang_worker.SGLangGenerationWorker": ["sglang"],
+    "nemo_rl.models.generation.dynamo.dynamo_worker.DynamoVllmWorker": None,
+    "nemo_rl.models.policy.workers.dtensor_policy_worker.DTensorPolicyWorker": ["fsdp"],
+    "nemo_rl.models.policy.workers.dtensor_policy_worker_v2.DTensorPolicyWorkerV2": [
+        "automodel"
+    ],
+    "nemo_rl.models.value.workers.dtensor_value_worker_v2.DTensorValueWorkerV2": [
+        "automodel"
+    ],
+    "nemo_rl.models.policy.workers.megatron_policy_worker.MegatronPolicyWorker": [
+        "mcore"
+    ],
+    "nemo_rl.models.value.workers.megatron_value_worker.MegatronValueWorker": ["mcore"],
+    "nemo_rl.data.energon.sft_worker.SFTMegatronPolicyWorker": ["mcore"],
+    "nemo_rl.models.generation.trtllm.trtllm_worker_async.TrtllmAsyncGenerationWorker": [
+        "trtllm"
+    ],
+    "nemo_rl.environments.math_environment.MathEnvironment": None,
+    "nemo_rl.environments.math_environment.MathMultiRewardEnvironment": None,
+    "nemo_rl.environments.vlm_environment.VLMEnvironment": None,
+    "nemo_rl.environments.code_environment.CodeEnvironment": None,
+    "nemo_rl.environments.reward_model_environment.RewardModelEnvironment": None,
+    "nemo_rl.environments.code_jaccard_environment.CodeJaccardEnvironment": None,
+    "nemo_rl.environments.games.sliding_puzzle.SlidingPuzzleEnv": None,
+    # AsyncTrajectoryCollector needs the vLLM environment to handle exceptions
+    # from VllmGenerationWorker.
+    "nemo_rl.algorithms.async_utils.AsyncTrajectoryCollector": ["vllm"],
+    # ReplayBuffer needs the vLLM environment to handle trajectory data from
+    # VllmGenerationWorker.
+    "nemo_rl.algorithms.async_utils.ReplayBuffer": ["vllm"],
+    # SyncRolloutActor doesn't import vllm directly -- policy_generation is a Ray
+    # actor handle. The vLLM env is needed because (1) transfer_queue is bundled
+    # into the vLLM venv (and the policy training venvs), and the actor writes
+    # flattened tensors to TQ via dp_client.put_samples; (2) same-node colocation
+    # with VllmGenerationWorker avoids duplicate venv caches.
+    "nemo_rl.experience.sync_rollout_actor.SyncRolloutActor": ["vllm"],
+    "nemo_rl.environments.tools.retriever.RAGEnvironment": None,
+    "nemo_rl.environments.nemo_gym.NemoGym": ["nemo_gym"],
+    # ModelOpt quantization-aware workers
+    "nemo_rl.modelopt.models.generation.vllm_quant_worker.VllmQuantGenerationWorker": [
+        "modelopt",
+        "vllm",
+    ],
+    "nemo_rl.modelopt.models.generation.vllm_quant_worker.VllmQuantAsyncGenerationWorker": [
+        "modelopt",
+        "vllm",
+    ],
+    "nemo_rl.modelopt.models.policy.workers.dtensor_quant_policy_worker.DTensorQuantPolicyWorker": [
+        "modelopt",
+        "automodel",
+    ],
+    "nemo_rl.modelopt.models.policy.workers.dtensor_quant_policy_worker_v2.DTensorQuantPolicyWorkerV2": [
+        "modelopt",
+        "automodel",
+    ],
+    "nemo_rl.modelopt.models.policy.workers.megatron_quant_policy_worker.MegatronQuantPolicyWorker": [
+        "modelopt",
+        "mcore",
+    ],
+}
+
+
+def _build_stage(extras: list[str]) -> str:
+    """Which image layer can finish this venv.
+
+    The tensorrt_llm wheel is only built in the TRT-LLM layer, so those venvs get
+    their third-party packages in two steps; everything else finishes in the
+    dependency layer.
+    """
+    return "trtllm" if "trtllm" in extras else "deps"
+
+
+def main(argv: list[str]) -> int:
+    r"""Print "<actor FQN>\t<stage>\t<uv sync extra flags>" for uv-managed actors.
+
+    Usage: actor_environments.py [<stage>] [<skip extra> ...]
+
+    ``<stage>`` is "deps" or "trtllm" (omit for all). Any extras listed after it
+    are skipped, which is how the Dockerfile honors SKIP_VLLM_BUILD and friends.
+    Filtering on the declared extras -- rather than on a substring of the actor
+    name -- is what makes SKIP_VLLM_BUILD also skip actors like
+    AsyncTrajectoryCollector, whose name contains no "vllm".
+    """
+    stage = argv[1] if len(argv) > 1 and argv[1] != "all" else None
+    if stage not in (None, "deps", "trtllm"):
+        print(f"unknown stage: {stage!r}", file=sys.stderr)
+        return 2
+    skip = set(argv[2:])
+    unknown = skip - {e for extras in ACTOR_ENVIRONMENTS.values() for e in extras or ()}
+    if unknown:
+        print(f"unknown extras: {sorted(unknown)}", file=sys.stderr)
+        return 2
+    for actor_fqn, extras in sorted(ACTOR_ENVIRONMENTS.items()):
+        if extras is None or skip & set(extras):
+            continue
+        actor_stage = _build_stage(extras)
+        if stage is not None and actor_stage != stage:
+            continue
+        flags = " ".join(f"--extra {extra}" for extra in extras)
+        print(actor_fqn, actor_stage, flags, sep="\t")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))
diff --git a/nemo_rl/distributed/ray_actor_environment_registry.py b/nemo_rl/distributed/ray_actor_environment_registry.py
index dbad277abb..94d8c9fe60 100644
--- a/nemo_rl/distributed/ray_actor_environment_registry.py
+++ b/nemo_rl/distributed/ray_actor_environment_registry.py
@@ -12,49 +12,55 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from nemo_rl.distributed.virtual_cluster import PY_EXECUTABLES
+import tomllib
+from pathlib import Path
 
+from nemo_rl.distributed.actor_environments import ACTOR_ENVIRONMENTS
+from nemo_rl.distributed.virtual_cluster import (
+    PY_EXECUTABLES,
+    git_root,
+    uv_py_executable,
+)
+
+# Actor FQN -> the py_executable its workers launch under. The extras come from
+# nemo_rl.distributed.actor_environments, which docker/Dockerfile also reads to
+# pre-build one venv per actor into the image.
+#
+# NEMO_RL_PY_EXECUTABLES_SYSTEM=1 is not checked here. PY_EXECUTABLES and
+# uv_py_executable both already return the driver's interpreter when it is set,
+# so there is one place that knows about the flag rather than two.
 ACTOR_ENVIRONMENT_REGISTRY: dict[str, str] = {
-    "nemo_rl.models.generation.vllm.vllm_worker.VllmGenerationWorker": PY_EXECUTABLES.VLLM_GYM,
-    "nemo_rl.models.generation.vllm.vllm_worker_async.VllmAsyncGenerationWorker": PY_EXECUTABLES.VLLM_GYM,
-    "nemo_rl.models.generation.sglang.sglang_worker.SGLangGenerationWorker": PY_EXECUTABLES.SGLANG,
-    "nemo_rl.models.generation.trtllm.trtllm_worker_async.TrtllmAsyncGenerationWorker": PY_EXECUTABLES.TRTLLM,
-    "nemo_rl.models.generation.dynamo.dynamo_worker.DynamoVllmWorker": PY_EXECUTABLES.SYSTEM,
-    "nemo_rl.models.policy.workers.dtensor_policy_worker.DTensorPolicyWorker": PY_EXECUTABLES.FSDP,
-    "nemo_rl.models.policy.workers.dtensor_policy_worker_v2.DTensorPolicyWorkerV2": PY_EXECUTABLES.AUTOMODEL,
-    "nemo_rl.models.value.workers.dtensor_value_worker_v2.DTensorValueWorkerV2": PY_EXECUTABLES.AUTOMODEL,
-    "nemo_rl.models.policy.workers.megatron_policy_worker.MegatronPolicyWorker": PY_EXECUTABLES.MCORE,
-    "nemo_rl.models.value.workers.megatron_value_worker.MegatronValueWorker": PY_EXECUTABLES.MCORE,
-    "nemo_rl.data.energon.sft_worker.SFTMegatronPolicyWorker": PY_EXECUTABLES.MCORE,
-    "nemo_rl.environments.math_environment.MathEnvironment": PY_EXECUTABLES.SYSTEM,
-    "nemo_rl.environments.math_environment.MathMultiRewardEnvironment": PY_EXECUTABLES.SYSTEM,
-    "nemo_rl.environments.vlm_environment.VLMEnvironment": PY_EXECUTABLES.SYSTEM,
-    "nemo_rl.environments.code_environment.CodeEnvironment": PY_EXECUTABLES.SYSTEM,
-    "nemo_rl.environments.reward_model_environment.RewardModelEnvironment": PY_EXECUTABLES.SYSTEM,
-    "nemo_rl.environments.code_jaccard_environment.CodeJaccardEnvironment": PY_EXECUTABLES.SYSTEM,
-    "nemo_rl.environments.games.sliding_puzzle.SlidingPuzzleEnv": PY_EXECUTABLES.SYSTEM,
-    # AsyncTrajectoryCollector needs vLLM environment to handle exceptions from VllmGenerationWorker
-    "nemo_rl.algorithms.async_utils.AsyncTrajectoryCollector": PY_EXECUTABLES.VLLM,
-    # ReplayBuffer needs vLLM environment to handle trajectory data from VllmGenerationWorker
-    "nemo_rl.algorithms.async_utils.ReplayBuffer": PY_EXECUTABLES.VLLM,
-    # SyncRolloutActor doesn't import vllm directly — policy_generation is a
-    # Ray actor handle. The VLLM env is needed because (1) transfer_queue is
-    # bundled into the VLLM venv (and the policy training venvs), and the
-    # actor writes flattened tensors to TQ via dp_client.put_samples;
-    # (2) same-node colocation with VllmGenerationWorker avoids duplicate
-    # venv caches.
-    "nemo_rl.experience.sync_rollout_actor.SyncRolloutActor": PY_EXECUTABLES.VLLM,
-    "nemo_rl.environments.tools.retriever.RAGEnvironment": PY_EXECUTABLES.SYSTEM,
-    "nemo_rl.environments.nemo_gym.NemoGym": PY_EXECUTABLES.NEMO_GYM,
-    # ModelOpt actors need the modelopt extra on top of their backend extra.
-    "nemo_rl.modelopt.models.generation.vllm_quant_worker.VllmQuantGenerationWorker": PY_EXECUTABLES.MODELOPT_VLLM,
-    "nemo_rl.modelopt.models.generation.vllm_quant_worker.VllmQuantAsyncGenerationWorker": PY_EXECUTABLES.MODELOPT_VLLM,
-    "nemo_rl.modelopt.models.policy.workers.dtensor_quant_policy_worker.DTensorQuantPolicyWorker": PY_EXECUTABLES.MODELOPT_AUTOMODEL,
-    "nemo_rl.modelopt.models.policy.workers.dtensor_quant_policy_worker_v2.DTensorQuantPolicyWorkerV2": PY_EXECUTABLES.MODELOPT_AUTOMODEL,
-    "nemo_rl.modelopt.models.policy.workers.megatron_quant_policy_worker.MegatronQuantPolicyWorker": PY_EXECUTABLES.MODELOPT_MCORE,
+    actor_fqn: PY_EXECUTABLES.SYSTEM if extras is None else uv_py_executable(extras)
+    for actor_fqn, extras in ACTOR_ENVIRONMENTS.items()
 }
 
 
+def _reject_undeclared_extras() -> None:
+    """Fail at import if an actor names an extra that does not exist.
+
+    Without this a typo like "mcore2" builds a valid-looking
+    ``uv run --locked --extra mcore2 ...`` and only fails when that actor first
+    launches -- and during an image build not even then, because
+    nemo_rl/utils/prefetch_venvs.py catches the per-actor error and exits 0.
+    The check lives here rather than in actor_environments.py because that module
+    must stay dependency-free: docker/Dockerfile runs it from a layer where the
+    rest of the source tree does not exist.
+    """
+    with open(Path(git_root) / "pyproject.toml", "rb") as f:
+        declared = set(tomllib.load(f)["project"]["optional-dependencies"])
+    for actor_fqn, extras in ACTOR_ENVIRONMENTS.items():
+        unknown = set(extras or ()) - declared
+        if unknown:
+            raise ValueError(
+                f"{actor_fqn!r} in nemo_rl/distributed/actor_environments.py names "
+                f"extras {sorted(unknown)} that are not in "
+                "[project.optional-dependencies] of pyproject.toml"
+            )
+
+
+_reject_undeclared_extras()
+
+
 def get_actor_python_env(actor_class_fqn: str) -> str:
     if actor_class_fqn in ACTOR_ENVIRONMENT_REGISTRY:
         return ACTOR_ENVIRONMENT_REGISTRY[actor_class_fqn]
@@ -62,9 +68,10 @@ def get_actor_python_env(actor_class_fqn: str) -> str:
         raise ValueError(
             f"No actor environment registered for {actor_class_fqn}. "
             f"You're attempting to create an actor ({actor_class_fqn}) "
-            "without specifying a python environment for it. Please either"
-            "specify a python environment in the registry "
-            "(nemo_rl.distributed.ray_actor_environment_registry.ACTOR_ENVIRONMENT_REGISTRY) "
+            "without specifying a python environment for it. Please either "
+            "add the actor to ACTOR_ENVIRONMENTS in nemo_rl/distributed/actor_environments.py, "
+            "register it at runtime with ACTOR_ENVIRONMENT_REGISTRY[fqn] = <py_executable> "
+            "(the path for workers defined outside this repo), "
             "or pass a py_executable to the RayWorkerBuilder. If you're unsure about which "
             "environment to use, a good default is PY_EXECUTABLES.SYSTEM for ray actors that "
             "don't have special dependencies. If you do have special dependencies (say, you're "
diff --git a/nemo_rl/distributed/virtual_cluster.py b/nemo_rl/distributed/virtual_cluster.py
index 75f9ea1051..b3c4f96af9 100644
--- a/nemo_rl/distributed/virtual_cluster.py
+++ b/nemo_rl/distributed/virtual_cluster.py
@@ -16,7 +16,7 @@
 import socket
 import sys
 import time
-from typing import NamedTuple, NotRequired, Optional, TypedDict
+from typing import NamedTuple, NotRequired, Optional, Sequence, TypedDict
 
 import ray
 from ray.util.placement_group import (
@@ -118,6 +118,19 @@ def _resolve_system_overrides(cls) -> None:
 PY_EXECUTABLES._resolve_system_overrides()
 
 
+def uv_py_executable(extras: Sequence[str]) -> str:
+    """py_executable of a uv-managed venv with the given extras (same shape as PY_EXECUTABLES.*).
+
+    Honors NEMO_RL_PY_EXECUTABLES_SYSTEM the same way the PY_EXECUTABLES constants do.
+    The check has to live here as well: _resolve_system_overrides rewrites the class
+    attributes, but this builds a fresh string, so the rewrite cannot reach it.
+    """
+    if os.environ.get("NEMO_RL_PY_EXECUTABLES_SYSTEM", "0") == "1":
+        return PY_EXECUTABLES.SYSTEM
+    extra_flags = "".join(f"--extra {extra} " for extra in extras)
+    return f"uv run --locked {extra_flags}--directory {git_root}"
+
+
 # Default port ranges — kept below the OS ephemeral range.  On some DGX/GB200
 # nodes the ephemeral floor is as low as 9000 (32768 on stock Linux), so every
 # service port is pinned below 9000 to avoid TOCTOU collisions.  See ray.sub for
diff --git a/nemo_rl/utils/prefetch_venvs.py b/nemo_rl/utils/prefetch_venvs.py
index 1bb444011f..d2f884d064 100755
--- a/nemo_rl/utils/prefetch_venvs.py
+++ b/nemo_rl/utils/prefetch_venvs.py
@@ -22,25 +22,25 @@
 from nemo_rl.utils.venvs import create_local_venv
 
 
-def prefetch_venvs(filters=None, negative_filters=None):
+def prefetch_venvs(filters=None):
     """Prefetch all virtual environments that will be used by workers.
 
     Args:
         filters: List of strings to match against actor FQNs. If provided, only
                 actors whose FQN contains at least one of the filter strings will
                 be prefetched. If None, all venvs are prefetched.
-        negative_filters: List of strings to exclude from prefetching. Actors whose
-                FQN contains any of these strings will be skipped.
+
+    Returns:
+        The FQNs whose venv failed to build. Empty when everything succeeded.
+        Callers are expected to treat a non-empty list as a failure -- see the
+        __main__ block, which exits 1.
     """
     print("Prefetching virtual environments...")
     if filters:
         print(f"Filtering for: {filters}")
-    if negative_filters:
-        print(f"Excluding: {negative_filters}")
 
     # Track statistics for summary
     skipped_by_filter = []
-    skipped_by_negative_filter = []
     skipped_system_python = []
     prefetched = []
     failed = []
@@ -52,10 +52,6 @@ def prefetch_venvs(filters=None, negative_filters=None):
         if filters and not any(f in actor_fqn for f in filters):
             skipped_by_filter.append(actor_fqn)
             continue
-        # Apply negative filters if provided
-        if negative_filters and any(f in actor_fqn for f in negative_filters):
-            skipped_by_negative_filter.append(actor_fqn)
-            continue
         # Skip system python as it doesn't need a venv
         if py_executable == "python" or py_executable == sys.executable:
             print(f"Skipping {actor_fqn} (uses system Python)")
@@ -97,10 +93,6 @@ def prefetch_venvs(filters=None, negative_filters=None):
         print(f"  Skipped (filtered out): {len(skipped_by_filter)}")
         for actor_fqn in skipped_by_filter:
             print(f"    - {actor_fqn}")
-    if negative_filters:
-        print(f"  Skipped (negative filter): {len(skipped_by_negative_filter)}")
-        for actor_fqn in skipped_by_negative_filter:
-            print(f"    - {actor_fqn}")
     if failed:
         print(f"  Failed: {len(failed)}")
         for actor_fqn in failed:
@@ -109,6 +101,8 @@ def prefetch_venvs(filters=None, negative_filters=None):
     # Create convenience python wrapper scripts for frozen environment support (container-only)
     create_frozen_environment_symlinks(venv_configs)
 
+    return failed
+
 
 def create_frozen_environment_symlinks(venv_configs):
     """Create python-{ClassName} wrapper scripts in /usr/local/bin for frozen environment support.
@@ -215,12 +209,6 @@ def create_frozen_environment_symlinks(venv_configs):
 
   # Prefetch multiple specific venvs
   python -m nemo_rl.utils.prefetch_venvs vllm policy environment
-
-  # Prefetch all venvs except vLLM-related ones
-  python -m nemo_rl.utils.prefetch_venvs --negative-filters vllm
-
-  # Prefetch all venvs except vLLM and SGLang
-  python -m nemo_rl.utils.prefetch_venvs --negative-filters vllm sglang
         """,
     )
     parser.add_argument(
@@ -230,15 +218,13 @@ def create_frozen_environment_symlinks(venv_configs):
         "contains at least one of these strings will be prefetched. "
         "If not provided, all venvs are prefetched.",
     )
-    parser.add_argument(
-        "--negative-filters",
-        nargs="*",
-        help="Filter strings to exclude from prefetching. Actors whose FQN "
-        "contains any of these strings will be skipped.",
-    )
     args = parser.parse_args()
 
-    prefetch_venvs(
-        filters=args.filters if args.filters else None,
-        negative_filters=args.negative_filters if args.negative_filters else None,
-    )
+    failed = prefetch_venvs(filters=args.filters if args.filters else None)
+    # Exit non-zero if any venv failed to build. The per-actor loop above keeps
+    # going after a failure so one broken venv does not hide the others, but the
+    # process must still fail: this runs in the image build, and exiting 0 here
+    # ships an image that is missing a venv, with the actor only dying the first
+    # time someone launches it.
+    if failed:
+        raise SystemExit(1)
diff --git a/nemo_rl/utils/venvs.py b/nemo_rl/utils/venvs.py
index 6e632b8d9f..61e44444e4 100644
--- a/nemo_rl/utils/venvs.py
+++ b/nemo_rl/utils/venvs.py
@@ -123,8 +123,13 @@ def create_local_venv(
     # Command doesn't matter, since `uv` syncs the environment no matter the command.
     exec_cmd.extend(["echo", f"Finished creating venv {venv_path}"])
 
-    # Always run uv sync first to ensure the build requirements are set (for --no-build-isolation packages)
-    subprocess.run(["uv", "sync", "--directory", git_root], env=env, check=True)
+    # Run uv sync first to ensure build requirements are set (for --no-build-isolation packages).
+    # --inexact: this base-set sync must not prune extras out of a venv that was
+    # pre-materialized in the image; pruning and re-adding hardlinked packages would copy
+    # them up into the image's final layer.
+    subprocess.run(
+        ["uv", "sync", "--inexact", "--directory", git_root], env=env, check=True
+    )
     subprocess.run(exec_cmd, env=env, check=True)
 
     # Return the path to the python executable in the virtual environment
diff --git a/pyrefly.toml b/pyrefly.toml
index 1b54fdaab5..52d64fb3ee 100644
--- a/pyrefly.toml
+++ b/pyrefly.toml
@@ -150,6 +150,7 @@ project-includes = [
   "nemo_rl/data_plane/tq_token_sink.py",
   "nemo_rl/data_plane/worker_mixin.py",
   "nemo_rl/distributed/__init__.py",
+  "nemo_rl/distributed/actor_environments.py",
   "nemo_rl/distributed/collectives.py",
   "nemo_rl/distributed/held_port.py",
   "nemo_rl/distributed/named_sharding.py",
diff --git a/tests/unit/distributed/test_actor_environments.py b/tests/unit/distributed/test_actor_environments.py
new file mode 100644
index 0000000000..669e5118d9
--- /dev/null
+++ b/tests/unit/distributed/test_actor_environments.py
@@ -0,0 +1,293 @@
+# Copyright (c) 2026, NVIDIA CORPORATION.  All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Guards on ACTOR_ENVIRONMENTS, the actor -> uv extras table.
+
+docker/Dockerfile runs nemo_rl/distributed/actor_environments.py as a script from
+the dependency layer to decide which venvs to pre-build, and the runtime registry
+imports the same dict. These tests keep the two readers honest.
+"""
+
+import ast
+import hashlib
+import importlib.util
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from nemo_rl.distributed.actor_environments import ACTOR_ENVIRONMENTS, _build_stage
+from nemo_rl.distributed.ray_actor_environment_registry import (
+    ACTOR_ENVIRONMENT_REGISTRY,
+)
+from nemo_rl.distributed.virtual_cluster import (
+    PY_EXECUTABLES,
+    git_root,
+    uv_py_executable,
+)
+
+MODULE_PATH = Path(git_root) / "nemo_rl" / "distributed" / "actor_environments.py"
+
+# Read straight from the environment: since #4020 the flag is applied inside
+# PY_EXECUTABLES and uv_py_executable, so there is no module constant to import.
+USE_SYSTEM_EXECUTABLE = os.environ.get("NEMO_RL_PY_EXECUTABLES_SYSTEM", "0") == "1"
+
+
+@pytest.mark.parametrize("actor_fqn", sorted(ACTOR_ENVIRONMENTS))
+def test_actor_extras_is_none_or_a_list_of_str(actor_fqn):
+    """Each value is None or a list of strings.
+
+    This deliberately does NOT re-check that the extras are declared in
+    pyproject.toml. Importing this module imports the registry, which runs
+    _reject_undeclared_extras() at import time, so an undeclared extra raises
+    during collection and no assertion here is ever reached. A type error is
+    different: ("mcore",) is a tuple of a real extra, so the import-time check --
+    which only does set arithmetic -- passes it, and this is what catches it.
+    """
+    extras = ACTOR_ENVIRONMENTS[actor_fqn]
+    if extras is None:
+        return
+    assert isinstance(extras, list) and all(isinstance(e, str) for e in extras), (
+        f"{actor_fqn}: value must be None or a list of extras, got {extras!r}"
+    )
+
+
+@pytest.mark.parametrize("actor_fqn", sorted(ACTOR_ENVIRONMENTS))
+def test_actor_module_exists(actor_fqn):
+    """The FQN still points at a module that exists.
+
+    Parsed, not imported: most of these pull in vllm or megatron.
+    """
+    module_name, _, class_name = actor_fqn.rpartition(".")
+    path = Path(git_root) / (module_name.replace(".", "/") + ".py")
+    if not path.exists():
+        path = Path(git_root) / module_name.replace(".", "/") / "__init__.py"
+    assert path.exists(), f"{actor_fqn}: no module file for {module_name}"
+
+    defined = set()
+    for node in ast.walk(ast.parse(path.read_text())):
+        if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+            defined.add(node.name)
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            defined.update(a.asname or a.name.split(".")[-1] for a in node.names)
+    assert class_name in defined, f"{actor_fqn}: {class_name} not defined in {path}"
+
+
+@pytest.mark.skipif(
+    USE_SYSTEM_EXECUTABLE,
+    reason="NEMO_RL_PY_EXECUTABLES_SYSTEM=1 puts every actor on the driver interpreter",
+)
+def test_registry_matches_py_executables():
+    """The generated py_executable is the string the worker actually needs."""
+    expected = {
+        ("vllm",): PY_EXECUTABLES.VLLM,
+        ("vllm", "nemo_gym"): PY_EXECUTABLES.VLLM_GYM,
+        ("sglang",): PY_EXECUTABLES.SGLANG,
+        ("fsdp",): PY_EXECUTABLES.FSDP,
+        ("automodel",): PY_EXECUTABLES.AUTOMODEL,
+        ("mcore",): PY_EXECUTABLES.MCORE,
+        ("trtllm",): PY_EXECUTABLES.TRTLLM,
+        ("nemo_gym",): PY_EXECUTABLES.NEMO_GYM,
+    }
+    for actor_fqn, extras in ACTOR_ENVIRONMENTS.items():
+        got = ACTOR_ENVIRONMENT_REGISTRY[actor_fqn]
+        if extras is None:
+            assert got == PY_EXECUTABLES.SYSTEM, actor_fqn
+        else:
+            assert got == expected.get(tuple(extras), uv_py_executable(extras)), (
+                actor_fqn
+            )
+
+
+def test_every_extras_py_executable_is_wired_to_an_actor():
+    """A PY_EXECUTABLES constant naming extras must be used by some actor.
+
+    This branch builds ACTOR_ENVIRONMENT_REGISTRY from ACTOR_ENVIRONMENTS instead of
+    the literal dict main keeps in ray_actor_environment_registry.py. When main changes
+    which extras an actor needs -- as #4009 did, moving the vLLM workers onto
+    PY_EXECUTABLES.VLLM_GYM so token capture can import nemo_gym -- a rebase drops the
+    literal dict and the change is silently lost. A new constant that no actor uses is
+    the signature of exactly that miss.
+
+    PY_EXECUTABLES.BASE is excluded: it names no extra and is not an actor environment.
+    """
+    unused = []
+    for name in sorted(n for n in dir(PY_EXECUTABLES) if n.isupper()):
+        value = getattr(PY_EXECUTABLES, name)
+        if "--extra" not in value:
+            continue
+        if not any(
+            uv_py_executable(extras) == value
+            for extras in ACTOR_ENVIRONMENTS.values()
+            if extras is not None
+        ):
+            unused.append(name)
+    assert not unused, (
+        f"PY_EXECUTABLES {unused} name extras but no actor in ACTOR_ENVIRONMENTS uses "
+        "them. Either an actor's extras were not carried over from "
+        "nemo_rl/distributed/ray_actor_environment_registry.py on main, or the "
+        "constant is dead and should be deleted."
+    )
+
+
+def test_actor_environments_module_is_stdlib_only():
+    """docker/Dockerfile runs this module from the dependency layer.
+
+    Only pyproject.toml, uv.lock and a couple of nemo_rl files exist there, so an
+    import of anything else -- especially anything from nemo_rl -- breaks the image
+    build in its most expensive layer.
+    """
+    stdlib = set(sys.stdlib_module_names) | {"__future__"}
+    tree = ast.parse(MODULE_PATH.read_text())
+    for node in ast.walk(tree):
+        roots = []
+        if isinstance(node, ast.Import):
+            roots = [a.name.split(".")[0] for a in node.names]
+        elif isinstance(node, ast.ImportFrom):
+            roots = [(node.module or "").split(".")[0]]
+        for root in roots:
+            assert root in stdlib, (
+                f"{MODULE_PATH.name} imports {root!r}, which is not in the standard "
+                "library. This module must stay dependency-free -- docker/Dockerfile "
+                "runs it from a layer where only pyproject.toml and uv.lock exist."
+            )
+
+
+def test_script_rejects_a_typo_instead_of_printing_nothing():
+    """A mistyped stage or skip extra must fail, not emit an empty list.
+
+    The Dockerfile pipes this into a loop, so silently printing zero rows would
+    build zero venvs. `test -s` catches that in the deps layer, but the guard is
+    what makes the failure say which word was wrong.
+    """
+    for argv in (["badstage"], ["all", "notanextra"]):
+        proc = subprocess.run(
+            [sys.executable, str(MODULE_PATH), *argv],
+            capture_output=True,
+            text=True,
+            cwd=git_root,
+        )
+        assert proc.returncode == 2, f"{argv} should be rejected, got {proc.returncode}"
+        assert not proc.stdout.strip(), f"{argv} printed rows despite being invalid"
+
+
+def test_registry_import_rejects_an_undeclared_extra(monkeypatch):
+    """A typo'd extra must fail while IMPORTING the registry, not at venv creation.
+
+    On the image-build path `prefetch_venvs.py` catches the per-actor error and
+    exits 0, so without this guard a typo ships a green image missing one venv.
+    Importing the module fresh is the point -- calling the check directly would
+    still pass if nothing invoked it at import.
+    """
+    import nemo_rl.distributed.actor_environments as table
+
+    registry_path = (
+        Path(git_root) / "nemo_rl" / "distributed" / "ray_actor_environment_registry.py"
+    )
+
+    def _import_registry_fresh(name):
+        spec = importlib.util.spec_from_file_location(name, registry_path)
+        spec.loader.exec_module(importlib.util.module_from_spec(spec))
+
+    _import_registry_fresh("_registry_clean")  # real table: must not raise
+
+    monkeypatch.setattr(
+        table,
+        "ACTOR_ENVIRONMENTS",
+        {
+            **table.ACTOR_ENVIRONMENTS,
+            "nemo_rl.fake.Worker": ["definitely_not_an_extra"],
+        },
+    )
+    with pytest.raises(ValueError, match="definitely_not_an_extra"):
+        _import_registry_fresh("_registry_typo")
+
+
+def test_script_emits_the_stage_and_extra_flags_each_actor_needs():
+    """The script lists exactly the venvs the runtime expects, with the right columns.
+
+    The Dockerfile builds each venv from all three columns. Column 3 is what
+    `uv sync $extras` consumes, and column 2 is what the deps layer branches on to
+    leave the TRT-LLM venv base-only until its wheel exists. Comparing the whole
+    dict covers the actor list too, since dict equality requires the same keys.
+    """
+    proc = subprocess.run(
+        [sys.executable, str(MODULE_PATH), "all"],
+        capture_output=True,
+        text=True,
+        check=True,
+        cwd=git_root,
+    )
+    rows = {
+        line.split("\t")[0]: line.split("\t")[1:]
+        for line in proc.stdout.splitlines()
+        if line.strip()
+    }
+    expected = {
+        fqn: [_build_stage(extras), " ".join(f"--extra {e}" for e in extras)]
+        for fqn, extras in ACTOR_ENVIRONMENTS.items()
+        if extras is not None
+    }
+    assert rows == expected
+    assert (
+        rows[
+            "nemo_rl.models.generation.trtllm.trtllm_worker_async.TrtllmAsyncGenerationWorker"
+        ][0]
+        == "trtllm"
+    )
+
+
+def test_fingerprint_covers_the_actor_table():
+    """Editing an actor's extras must invalidate the container fingerprint.
+
+    Venvs at NEMO_RL_VENV_DIR are reused rather than rebuilt, and nothing prunes
+    them (the base sync runs --inexact and `uv run` is inexact by default). So a
+    changed extras list has to trip _check_container_fingerprint(), which is what
+    tells the user to set NRL_FORCE_REBUILD_VENVS=true.
+    """
+    spec = importlib.util.spec_from_file_location(
+        "_gen_fingerprint", Path(git_root) / "tools" / "generate_fingerprint.py"
+    )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    fingerprint = module.generate_fingerprint()
+    assert "nemo_rl/distributed/actor_environments.py" in fingerprint, (
+        "tools/generate_fingerprint.py must hash the actor -> extras table, or a "
+        "changed actor environment leaves a stale venv with no warning"
+    )
+    # Check the value is this file's hash, not merely present and non-empty --
+    # pointing the entry at some other file passes the weaker check.
+    assert (
+        fingerprint["nemo_rl/distributed/actor_environments.py"]
+        == hashlib.md5(MODULE_PATH.read_bytes()).hexdigest()
+    )
+
+
+def test_script_skips_by_extra_not_by_name():
+    """SKIP_VLLM_BUILD must drop actors that need vllm even without 'vllm' in the name."""
+    proc = subprocess.run(
+        [sys.executable, str(MODULE_PATH), "all", "vllm"],
+        capture_output=True,
+        text=True,
+        check=True,
+        cwd=git_root,
+    )
+    listed = {line.split("\t")[0] for line in proc.stdout.splitlines() if line.strip()}
+    assert "nemo_rl.algorithms.async_utils.AsyncTrajectoryCollector" not in listed
+    assert "nemo_rl.experience.sync_rollout_actor.SyncRolloutActor" not in listed
+    assert (
+        "nemo_rl.models.policy.workers.megatron_policy_worker.MegatronPolicyWorker"
+        in listed
+    )
diff --git a/tests/unit/utils/test_prefetch_venvs.py b/tests/unit/utils/test_prefetch_venvs.py
index 62c1886189..e7f70cd164 100644
--- a/tests/unit/utils/test_prefetch_venvs.py
+++ b/tests/unit/utils/test_prefetch_venvs.py
@@ -270,3 +270,37 @@ def test_prefetch_venvs_summary_with_failures(self, prefetch_venvs_func, capsys)
             assert "Venv prefetching complete! Summary:" in captured.out
             assert "Prefetched: 2" in captured.out
             assert "Failed: 1" in captured.out
+
+    def test_prefetch_venvs_returns_the_failed_actors(self, prefetch_venvs_func):
+        """A failed venv is reported to the caller, not just printed.
+
+        This runs during the image build. Before this returned anything, a venv
+        that failed to build was printed in the summary and then swallowed, so
+        the build went green and the actor only died the first time someone
+        launched it.
+        """
+        with patch(
+            "nemo_rl.utils.prefetch_venvs.create_local_venv"
+        ) as mock_create_venv:
+            mock_create_venv.side_effect = [
+                Exception("Test error"),
+                "/path/to/venv/bin/python",
+                "/path/to/venv/bin/python",
+            ] * CALL_MULTIPLIER
+
+            failed = prefetch_venvs_func(filters=None)
+
+        assert failed == [
+            "nemo_rl.models.generation.vllm.vllm_worker.VllmGenerationWorker"
+        ]
+
+    def test_prefetch_venvs_returns_empty_when_all_succeed(self, prefetch_venvs_func):
+        """The success path must stay falsy, or every build would fail."""
+        with patch(
+            "nemo_rl.utils.prefetch_venvs.create_local_venv"
+        ) as mock_create_venv:
+            mock_create_venv.return_value = "/path/to/venv/bin/python"
+
+            failed = prefetch_venvs_func(filters=None)
+
+        assert failed == []
diff --git a/tools/generate_fingerprint.py b/tools/generate_fingerprint.py
index 2a23578804..4cabfb0db3 100755
--- a/tools/generate_fingerprint.py
+++ b/tools/generate_fingerprint.py
@@ -109,6 +109,7 @@ def generate_fingerprint() -> dict[str, str]:
         Dictionary mapping component names to their hashes/commits:
         - "pyproject.toml": MD5 hash of pyproject.toml
         - "uv.lock": MD5 hash of uv.lock
+        - "nemo_rl/distributed/actor_environments.py": MD5 hash of the actor -> extras table
         - "submodules/<path>": Commit SHA for each submodule
     """
     repo_root = get_repo_root()
@@ -121,6 +122,15 @@ def generate_fingerprint() -> dict[str, str]:
     # Hash uv.lock
     fingerprint["uv.lock"] = compute_file_hash(repo_root / "uv.lock")
 
+    # Hash the actor -> uv extras table. Changing an actor's extras changes what its
+    # pre-built venv should contain, and venvs are reused rather than rebuilt, so this
+    # has to invalidate the fingerprint the same way a dependency change does.
+    # Without it a stale venv keeps packages from the extra the actor no longer declares
+    # and nothing tells the user to set NRL_FORCE_REBUILD_VENVS=true.
+    fingerprint["nemo_rl/distributed/actor_environments.py"] = compute_file_hash(
+        repo_root / "nemo_rl" / "distributed" / "actor_environments.py"
+    )
+
     # Get submodule SHAs (sorted by path for consistency)
     submodules = get_submodule_shas(repo_root)
     for path, sha in sorted(submodules.items()):