Artifact readiness, and five defects it turned up

[tactino]

Artifact-readiness work, and five defects it turned up. Two of them stopped
the package doing its job at all.

Three environment families could not start

atari, classic and robomimic never defined an action space. The
rollout refactor of 2026-03-20 introduced _get_action_spec, which requires
one, so:

$ plugrl-run-env-client classic-v1
ValueError: Env must expose action space via single_action_space/action_space

Nothing caught it because the only environment the test suite exercised was
the one that happened to define a space. classic-v1 now completes episodes,
and tests/test_action_space_contract.py constructs every registered
environment and makes the same call rollout makes. (d4rl defines it as a
property, which is easy to miss when grepping for an assignment — three
families, not four.)

_get_action_spec was guessing at a batch axis

It asked whether the leading axis of single_action_space happened to equal
num_envs, and stripped it if so. But single_action_space is unbatched by
Gymnasium's own definition, and every environment family here declares it
that way — so the branch could only ever be a false positive. It fires
whenever an action dimension coincides with the environment count, which for
a 7-DoF arm means --num-envs 7, and silently drops a real dimension.

Found by writing tests for the protocol's exchange rules, where two
environments with a two-dimensional action hit it immediately.

A finished run ended in a traceback

Running a server for N steps and pointing a client at it is the documented
happy path. It ended like this:

plugrl_env_client.agent.websocket_env_client_agent.ServerStopped:
Server requested env client shutdown after algorithm stop.

exit 1, on a run where the server had just saved its checkpoint and shut
down cleanly. ServerStopped is a normal end condition — its own docstring
says so. Worse under run_multiprocess: a non-zero child exit makes the
parent terminate its siblings, so one process seeing the stop first tore the
others down mid-episode. Anything that is not a server stop still
propagates, and there is a test for that.

There was no seeding at all

Bare env.reset(), no seed on RunnerArgs, DummyEnv drawing from global
np.random. "Three seeds per configuration" was not something this package
could deliver. Now: --runner.seed, threaded to the first reset only so the
whole rollout is reproducible rather than just its first episode, and
derive_process_seed gives each client process a disjoint slice — handing
every process the same base seed would have them replay one trajectory,
which looks like data collection and is not.

robomimic raises on a seed rather than accepting one, because robosuite's
randomness is not reachable from there. Refusing beats pretending.

A bare install could not import

Optional extras leaked into the base install path, and a dead
remote_viewer_wrapper imported an undeclared PIL. Both fixed; every git
dependency is now pinned to a full commit SHA, so a fresh clone resolves to
what was tested.

Tests worth reviewing rather than skimming

• test_terminal_observation.py — BaseEnv declares
  AutoresetMode.NEXT_STEP, which is a promise rollout depends on: the done
  step returns the terminal observation. An environment that resets inside
  its own step() breaks it silently, and the only symptom is corrupt
  training data. None of the six do; these tests pin that, and a deliberately
  misbehaving fake demonstrates the corruption executably.
• test_protocol_alternation.py — makes three claims from
  plugrl-protocol/SPEC.md observable rather than derived, by recording every
  message rollout would put on the wire: strict alternation; a feedback env
  set that need not match the infer's, and can name an environment the infer
  did not; chunk-summed reward. Each has a companion test for the
  configuration that hides it — equal episode lengths keep the sets equal,
  and a horizon of 1 makes chunk reward equal step reward.

Also

Apache-2.0, CI (lint + test), CITATION.cff, README corrected to match the
package, rollout timing exported to summary.json with per-stage fractions,
and the server's metadata message logged at startup with a warning when
replan_steps exceeds the reported action horizon.

Tests: 112 passing, 8 skipped.

---

🤖 Generated with Claude Code