@cluster(environment=...) and conda_env_name never reach the job script

[jeremymanning]

Summary

Selecting a pre-existing named conda environment on the cluster does not work. Both routes are accepted and discarded:

• @cluster(environment="myenv") — documented at decorator.py:48 as "Conda environment name"
• configure(conda_env_name="myenv") — a ClusterConfig field

>>> create_job_script("slurm", {**base, "environment": "from_decorator"}, "/scratch/job", cfg)
"from_decorator" in script  ->  False

>>> cfg = ClusterConfig(..., conda_env_name="from_config")
>>> create_job_script("slurm", base, "/scratch/job", cfg)
"from_config" in script      ->  False

Why

decorator.py:69 puts the value into job_config["environment"]. Nothing reads that key — measured across the package for both quote styles:

keys read from job_config: cluster_packages, cores, hf_flavor, hf_timeout, memory, partition, time

The config field fares no better. config.conda_env_name is read at exactly one place, utils.py:1168, inside setup_environment():

if config.conda_env_name:
    return f"conda run -n {config.conda_env_name} python"

and setup_environment() is called from exactly one place in the package — file_packaging.py:763. That module is orphaned: the #122 audit found zero importers outside __init__.py and its own tests. The execution path never reaches it.

What this does NOT mean

Remote environments are not broken. Environment replication works and is verified against real hardware. The two-venv path builds its own conda environments — clustrix_venv1_<key> and clustrix_venv2_<key> (utils.py:1556) — derived from the local environment being reproduced, and that is the mechanism the committed evidence exercises.

What is missing is the other thing: pointing a job at an environment that already exists on the cluster. On an HPC system with a curated module-loaded conda env, that is the normal way to work, and it is exactly what a user reading @cluster(environment="myenv") would expect to get.

The conda_env_name key also appears at utils.py:1579 and :1778, which reads like the setting is honoured. It is not — those lines assign the synthetic clustrix_venv2_<key> name into the returned dict, under a comment saying "for backward compatibility with job script generation". The user's value never enters that path.

Same family as #152, #158, #161

Accept the instruction, discard it, report success. A user sets environment="production", the job runs in a replicated environment instead, and nothing says otherwise. Unlike #161's inert fields, this one is not even documented as inert — decorator.py:48 describes it as working.

Options

1. Honour it. setup_environment() already contains the logic (conda run -n <name> python); the work is routing it into job_execution_lines and deciding precedence against replication. This is the option that matches what the parameter says it does.
2. Warn. Cheapest, and consistent with what @cluster(cores=N) on the local backend does not parallelize anything #152 and default_queue and @cluster(queue=...) are accepted and never read #158 just did.
3. Remove both. Honest, but removes a genuinely wanted capability rather than a vestigial one.

I would not choose (3): the capability is the normal HPC workflow. (1) needs a decision about precedence — if a user names an environment and replication is on, which wins, and does the other warn?

Definition of done

• @cluster(environment=...) and conda_env_name either reach the generated script or say they do not
• A test asserts the named environment appears in the script for the backends that support it — the reproduction above is four lines
• Precedence against environment replication is decided and documented
• docs/ updated (deferred to Master: documentation findings, deferred to a dedicated session #163 — a separate session owns documentation)