feat: add Rez PATH-shim queue environment with tool auto-discovery

[crowecawcaw]

Fixes: no issue yet — opening as a draft per CONTRIBUTING's "talk with us first" guidance, happy to file one if you'd prefer to track it there

What was the problem/requirement? (What/Why)

A customer reported that Rez does not work well with queue environments, because a queue environment runs in a single subprocess and the render command only receives environment variables harvested from it and replayed.

That is accurate, and it is structural rather than a bug. A queue environment action runs in its own subprocess, so the only channel into later actions is openjd_env: NAME=value directives. The existing rez_queue_env.yaml therefore activates a context, diffs the environment before and after, and replays the difference. Anything that is not a name-value pair does not survive.

A Rez alias is the clearest casualty. Rez implements it as an exported shell function, which Bash exports under a name like BASH_FUNC_launch%% with a multi-line value. The session runtime rejects that assignment outright:

openjd_env: "BASH_FUNC_demoalias%%=() {  demorender --via-alias \"$@\"\n}"
  -- ERROR: Failed to parse environment variable assignment.

So the alias is gone before any task runs. Ordered PATH edits are similarly fragile: the variable is restored, but a later environment that also edits PATH can reorder it.

What was the solution? (How)

A queue environment that wraps each task's command instead of exporting variables to it.

onEnter resolves the requested packages once, saves the context to a .rxt file in the session directory, asks Rez which executables those packages provide, and writes one shim per tool with the shim directory prepended to PATH:

#!/usr/bin/env bash
exec rez env --input "$REZ_CONTEXT_FILE" --shell bash -- "<tool>" "$@"

Job templates keep calling tools by bare name, such as command: mayapy, so each call re-enters the saved context in its own shell and Rez applies the full context inside the task's own process. Job bundles need no changes.

Tool names come from rez context -t on the saved context, so there is no hard-coded list of DCC executables. RezExtraTools covers commands a package provides without declaring them in its tools list.

This is a workaround for a specification gap, not a permanent design. RFC0008: Environment Wrap Actions proposes onWrapTaskRun, which does this properly; once it ships in the worker agent, the wrap hook replaces the shim directory and the PATH manipulation entirely. The README says so explicitly so nobody mistakes this for the intended long-term shape.

What is the impact of this change?

Additive. Three new files under queue_environments/rez_shim/, no changes to existing samples:

File	Purpose
rez_queue_env_shim.yaml	The queue environment to deploy on a farm
rez_demo_setup_queue_env.yaml	Test scaffolding: installs Rez and builds a demo package
demo_job_bundle/template.yaml	Verification job

The existing rez_queue_env.yaml is untouched and remains the right choice when packages only set variables, and the only choice on Windows.

Known tradeoffs, all documented in the README:

• Only bare command names are intercepted; an absolute path in a template bypasses the shims.
• Linux and macOS workers only. The shims are POSIX scripts relying on a shebang, so the environment fails immediately on Windows with a message pointing at rez_queue_env.yaml. I deliberately did not claim Windows support, since it is not tested.
• Each task pays a context re-entry, mitigated by Rez's resolve cache.
• The demo's package repository is created outside the session directory and persists on the worker; documented under cleanup.

How was this change tested?

Locally with openjd run, and end to end on a Deadline Cloud farm with a Linux service-managed fleet (on-demand, 2–4 vCPU). All templates pass openjd check, and python3 scripts/validate_repository.py passes.

The demo job proves its own thesis rather than asserting it. VerifyEnvironment runs three fidelity checks and fails the task on regression:

Check	State under test	Under harvest-and-replay
1	A plain variable	Survives
2	A Rez alias	Lost, rejected by the runtime
3	A PATH prepend shipping its own sort	Depends on environment order

Farm run, on the worker under job-user:

--------- Entering Environment: RezDemoSetup
Created demo Rez package 'demotool-1.0.0' in /tmp/rez-demo-repository
--------- Entering Environment: Rez
Created 3 Rez tool shims in /sessions/session-.../rez-shims:
   democonvert
   demorender
   demosleep
=== DEMOTOOL_VERSION as seen by the session (expected UNSET) ===
DEMOTOOL_VERSION=UNSET
=== DEMOTOOL_VERSION as seen inside the tool (expected 1.0.0) ===
demorender: DEMOTOOL_VERSION=1.0.0
=== Check 1: plain variable reaches the tool ===
PASS: variable visible inside the tool
=== Check 2: Rez alias survives into the task ===
PASS: alias is callable
=== Check 3: package PATH prepend shadows the system command ===
PASS: package command shadows the system one
All 3 environment fidelity checks passed.

UNSET in the session with 1.0.0 inside the tool is the core result: the variable was never harvested and replayed, Rez applied it inside the task's own process.

Cancelation was verified too, since it is the obvious risk with a wrapper. Rez runs the tool in a shell of its own, so the tree is shim → rez env → shell → tool rather than flat, but signals still propagate. Canceling the CancelThroughShim step on the farm:

demosleep: pid=39289 sleeping for 600s
Canceling subprocess 39247 via notify then terminate method
INTERRUPT: Sending signal "term" to process 39247
demosleep: caught SIGTERM, exiting
Process pid 39247 exited with code: 1

Task ended CANCELED with no orphans, so an application with its own signal handler gets to shut down cleanly.

Not tested: Windows (unsupported by design, guarded with a clear failure), and macOS workers on a real fleet — the macOS path was exercised locally only.

Was this change documented?

Yes. One README for the whole set at queue_environments/rez_shim/README.md, covering when to choose this over rez_queue_env.yaml, why the simpler sample cannot cover those cases, deployment, parameters, tradeoffs, the upstream RFC, and cleanup. The queue_environments index table points at the directory, matching how nested collections are handled elsewhere in the repo.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Removing the single-frame branch makes frame_range.split("-") crash on a single-value FrameRange.

FrameRange is a free-form LINE_EDIT STRING param and is also fed to the step as an OpenJD task range: "{{Param.FrameRange}}", which happily accepts a bare integer (e.g. FrameRange=5 to render one test frame). With this change, "5".split("-") returns ["5"] and the unpack start_s, end_s = args.frame_range.split("-") raises ValueError: not enough values to unpack. The task range stays valid, so OpenJD schedules the frame and the script then dies with a cryptic error instead of the previous graceful start = end = int(...).

The same removal in encode_movie.py and make_thumbnail.py has the identical failure mode. If single-frame ranges are meant to be unsupported now, consider validating FrameRange and emitting a clear message rather than letting the unpack throw.