gradlab 0.1.2__tar.gz → 0.2.2__tar.gz

{gradlab-0.1.2 → gradlab-0.2.2}/.gitignore

@@ -3,6 +3,10 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+output/
+tmp/
+docs/research/
+
 # Virtual environments and local package managers
 .venv/
 .venv*/

{gradlab-0.1.2 → gradlab-0.2.2}/METRICS.md

@@ -1,8 +1,15 @@
-# Metrics schema v19
+# Metrics schema v20
 
 This file is the source of truth for gradlab telemetry. The Python registry loads the table below
 and requires every emitted metric to match an exact registry entry or a bounded template.
 
+`Training Success` is a provisional Run classification produced by a Research Goal's declared
+threshold over training-time metrics. It is a cheap proxy used to classify and compare Runs; it
+does not establish that a Research Goal is solved. `Acceptance` is the separate determination from
+an Evaluated Goal's stricter checkpoint evaluation on seeds different from the training seeds.
+Only Acceptance can authorize Promotion, and neither metric delivery nor its W&B projection is the
+authority for that decision.
+
 ## Surfaces and dimensions
 
 - W&B is the authoritative scientific metric surface. One supervisor process inside the training
@@ -28,7 +35,7 @@ and requires every emitted metric to match an exact registry entry or a bounded
   `checkpoint_eval_contract`; the catalog must validate that expected absence against the immutable
   recipe and W&B run dimensions without suppressing otherwise compatible training-proxy history.
   Full-evaluation columns remain unavailable until verified checkpoint-evaluation evidence exists.
-- W&B config contains run-defining dimensions: `metrics_schema_version: 19`,
+- W&B config contains run-defining dimensions: `metrics_schema_version: 20`,
   `metrics_episode_window_size: 100`, `training_backend_id`,
   `training_backend_config_hash`, `algorithm_id`, goal,
   environment, starts, seed, frame skip, environment count, hyperparameters, eval protocol, and
@@ -36,9 +43,13 @@ and requires every emitted metric to match an exact registry entry or a bounded
   `dstack_coordinator_id`, `dstack_project`, `dstack_task`, and `attempt_id`; these are immutable
   run/attempt dimensions, not scientific metrics.
 - `experiments/goals/_workspaces.yaml` is the presentation source for managed W&B project
-  workspace views. It selects registered metrics without emitting aliases or changing their
-  scientific axes or semantics; every project resolved from an active checked-in goal inherits its
-  default profile unless the declaration assigns a complete project-specific profile.
+  workspace views. It selects registered metrics and derives each panel title from its exact metric
+  selectors without emitting aliases or changing their scientific axes or semantics; every project
+  resolved from an active checked-in goal inherits its default profile unless the declaration
+  assigns a complete project-specific profile. Project overrides omit panels or individual metric
+  selectors that do not apply to that project's active goals and recipes rather than rendering
+  empty placeholders. A managed line panel contains one distinct measure; only mutually exclusive
+  algorithm-specific variants of that same measure share a panel.
 - `goal_contract_sha256` is the semantic SHA-256 of the fully composed, rendered, validated goal
   contract. Generated goal reports use it with `goal_slug` to keep current-contract leaderboards
   comparable; noncurrent contracts are not queried or rendered.
@@ -64,10 +75,12 @@ and requires every emitted metric to match an exact registry entry or a bounded
   or its bounded in-browser history, are not emitted metrics, and must not be interpreted as aliases
   for similarly named W&B registry entries. `reward/provider` is the provider output before the
   task program and gradlab-owned reward transform; `reward/shaped` is the final policy-facing reward
-  after task shaping, scaling, and clipping. Playback computes realized return-to-go and `V(s) -
-  G(s)` only for a terminal, stochastic, policy-driven trajectory whose policy environment,
-  reward stream, discount, action sampling, and boundary/bootstrap semantics match training.
-  Otherwise those critic diagnostics are explicitly unavailable rather than numerically compared.
+  after task shaping, scaling, and clipping. Playback computes return-to-go and `V(s) - G(s)` only
+  for a completed, stochastic, policy-driven trajectory whose policy environment, reward stream,
+  discount, action sampling, and boundary/bootstrap semantics match training. True terminations use
+  a zero terminal value; truncations use the checkpoint critic's value of the exact final policy
+  input and display that bootstrap explicitly. Otherwise those critic diagnostics are explicitly
+  unavailable rather than numerically compared.
 
 The active checkpoint protocol is `acceptance`; complete accepted evidence additionally emits the
 `full` metric family. Dimension IDs must be unique and match `[A-Za-z0-9_.-]+`; unsafe IDs are
@@ -103,7 +116,7 @@ Asynchronous evaluations may arrive after later training rows without changing t
 X-axis. Each producer writes only its applicable scientific axis; durable delivery order uses
 `orchestration/event/sequence`.
 
-Current runs declare schema v19, and the supervisor validates and emits only v19 names. GradLab
+Current runs declare schema v20, and the supervisor validates and emits only v20 names. GradLab
 does not read, project, or preserve noncurrent W&B or R2 schemas.
 
 All metrics whose path contains `rolling` use the run-configured
@@ -124,7 +137,16 @@ metric path. `cumulative` explicitly means all eligible observations seen so far
   absent from the policy observation, visually similar early and late states are aliased for the
   critic, which can amplify the terminal-horizon discrepancy. Learner explained variance uses its
   rollout value targets and is not the same statistic as a single playback trajectory's
-  `V(s) - G(s)`.
+  `V(s) - G(s)`. A true termination closes the return with zero future value. A truncation does not:
+  the unobserved continuation prevents a fully realized Monte Carlo `G(s)`, but a
+  truncation-compatible N-step diagnostic can close the trace with the exact final policy input's
+  critic value: `Ĝ_t = r_t + γ r_{t+1} + … + γ^{T-t} V(s_T)`. That quantity is partly bootstrapped,
+  not a fully realized return or generally the learner's GAE lambda-return, and is valid for critic
+  comparison only when the final observation, preprocessing and conditioning, checkpoint critic,
+  discount, and truncation semantics match the training value contract. Playback labels this
+  bootstrap when it computes the diagnostic and withholds the comparison if the exact final-state
+  critic value is unavailable; treating truncation as termination by substituting a zero bootstrap
+  would fabricate a misleading residual.
 - Mario recipes disable automatic checkpoint evaluation and stop when
   `train/outcome/success/starts/all/rolling/rate/min` first reaches one. For a single start,
   that means 100 consecutive genuine target-origin clears; for multiple starts, every configured
@@ -170,8 +192,11 @@ metric path. `cumulative` explicitly means all eligible observations seen so far
   action-space-only minimum or maximum. The bounds remain a pure policy-space calculation used by
   diagnostics and are not duplicated as W&B metrics.
 - Actor-critic explained variance is `1 - Var(value_target - value_prediction) /
-  Var(value_target)`: one is perfect, zero means the critic explains no more target variance than a
-  constant baseline, and negative values are worse than that baseline. A near-zero value is not by
+  Var(value_target)`: one means the residual variance is zero (perfect up to a constant prediction
+  offset), zero means the critic explains no more target variance than a constant baseline, and
+  negative values are worse than that baseline. Because variance centers the residuals, explained
+  variance alone does not detect constant value bias; pair it with residual bias or calibration
+  measures when absolute accuracy matters. A near-zero value is not by
   itself evidence of exploding value loss. Pair it with value-prediction and advantage dispersion:
   predictions with much less dispersion than the residual advantages indicate a mostly
   state-insensitive baseline, while tiny target variance can make the ratio ill-conditioned.
@@ -198,6 +223,28 @@ metric path. `cumulative` explicitly means all eligible observations seen so far
   evaluation performance. A threshold condition with `progress_baseline` additionally emits
   `train/early_stop/{condition}/target/progress` as the current metric's clamped fraction from that
   baseline to its threshold. Only goal-owned checkpoint evaluation may establish acceptance.
+- `train/episode/length/origin/all/rolling/mean` counts policy transitions, so one step represents
+  four native frames in the current Breakout contract. It combines target- and archive-origin
+  episodes and is therefore not a clean survival comparison when archive curricula differ. Within
+  identical start, frame-skip, reset, and termination contracts, increasing length can indicate
+  better ball defense when target return or progress also improves and failure-reason rates do not;
+  it can instead reflect delayed serving, low-progress play, or the episode cap, while faster wall
+  completion can shorten a successful episode. Treat it as a diagnostic, not a monotonic success or
+  acceptance measure.
+- Breakout declares `score` as reward-independent episode progress.
+  `train/progress/score/origin/target/rolling/mean` is the mean terminal provider-native Atari
+  score over the most recent target-origin episodes, including warm-up before the 100-episode
+  window is full. GradLab-owned life-loss and serve-stall penalties do not change it. Atari score
+  weights brick rows differently, so this metric is not a brick count; it remains an online
+  behavior-policy training proxy rather than frozen-checkpoint evaluation evidence.
+- Breakout also declares `bricks_destroyed` and `bricks_destroyed_normalized` as
+  reward-independent episode progress. Their `train/progress/{progress}/origin/target/rolling/mean`
+  metrics average the terminal cumulative values over the most recent 100 target-origin episodes,
+  while `train/progress/{progress}/origin/target/rolling/max` reports the maximum over that same
+  window. The normalized value is the `0.0..1.0` two-wall completion fraction. Both statistics
+  include warm-up before the window is full and are online behavior-policy training proxies rather
+  than frozen-checkpoint evaluation evidence. Breakout ranks runs first by the rolling maximum
+  terminal `bricks_destroyed` count, then by the earliest training step.
 - Training episode reduction aggregates return, length, outcome, success, the explicitly supported
   target-origin cell-novelty statistic, and goal-declared numeric episode progress fields.
   Progress field names refer to task-semantic signals and must be populated independently of the
@@ -217,11 +264,19 @@ metric path. `cumulative` explicitly means all eligible observations seen so far
   between-rollout time includes optimizer updates, callbacks, and logging, so it is deliberately
   not named optimization time. The corresponding rates are
   `train/throughput/loop/rate` and `train/throughput/provider/step/rate`.
-- Reward components are emitted only when active. Each component has mean, nonzero rate, and share;
+- Reward components are emitted only when configured. Each component mean includes every policy
+  transition in the rollout, including zero-valued transitions; nonzero rate separately reports
+  the fraction on which the component contributed. Each component also has an absolute share;
   raw reward appears only when it differs from shaped reward. Mario's `progress` component includes
   both its base new-progress reward and any configured additional new-progress reward above
-  `progress_reward_boost_start_x`. ViZDoom Deathmatch's optional `sample-factory-v0` shape exposes
-  `kill`, `death`, `hit`, `damage`, `health`, `armor`, `weapon`, `ammo`, and `weapon_hold`
+  `progress_reward_boost_start_x`. An identity task's `event` component is the sum of its declared
+  signed `event_rewards` for events firing on that transition. Its per-event reward metrics split
+  that sum by declared event. An identity `equals` event contributes on every policy transition
+  whose post-transition signal matches; `previous_equals` contributes when the signal at the start
+  of the transition matches, using the reset signal on the first transition when available;
+  `equals_for` contributes only when the consecutive-match counter first reaches its threshold.
+  ViZDoom Deathmatch's optional `sample-factory-v0` shape
+  exposes `kill`, `death`, `hit`, `damage`, `health`, `armor`, `weapon`, `ammo`, and `weapon_hold`
   components; their sum is the pre-transform task reward and excludes the replaced provider reward.
 - The player's protocol-v8 Reward analysis ledger is local playback telemetry, not a W&B metric.
   It shows raw component values, multiplies each impact by the unit-interval reward scale,
@@ -254,9 +309,11 @@ metric path. `cumulative` explicitly means all eligible observations seen so far
 - Episode-return means are neither a best-episode metric nor the score of a currently visible lane:
   they reduce the configured recent episode window across all applicable vector lanes. W&B chart
   smoothing, when enabled, is applied on top of that already-rolling value. Under the root Breakout
-  contract (`reward_mode: native`, unclipped), shaped episode return is the sum of Atari row-score
-  deltas, so individual 400-plus games can coexist with a much lower mean when other lanes finish
-  with lower scores.
+  goal contract (`reward_mode: native`, unclipped), shaped episode return is the sum of Atari
+  row-score deltas unless a recipe declares additional shaping. The checked-in Breakout `ppo`
+  recipe subtracts five through its `event` reward component whenever `lives` decreases, so its
+  shaped episode return is native score minus five per life lost. Individual 400-plus games can
+  coexist with a much lower mean when other lanes finish with lower scores.
 - Episode returns, success rates, failure reasons, policy entropy, and optimizer diagnostics
   describe performance or mechanism; no one of them should be treated as a generic stall-stop
   signal. A configured plateau condition may watch any registered numeric training metric, with
@@ -353,10 +410,13 @@ unevaluated for future explicit user action. dstack process exit alone is never
 |---|---|---|---|---|---|---|
 | `train/episode/return/shaped/origin/target/rolling/mean` | Recent target return mean | Mean shaped return over the most recent genuine target-origin episodes, including warm-up before the configured window is full. | return | rollout | history | last |
 | `train/episode/return/shaped/origin/target/rolling/max` | Recent target return max | Maximum shaped return over the same recent target-origin episodes as the rolling mean. | return | rollout | history | last |
-| `train/episode/length/origin/all/rolling/mean` | Recent episode length mean | Mean length over the most recent genuine completed episodes across target and archive origins. | steps | rollout | history | last |
+| `train/episode/length/origin/all/rolling/mean` | Recent episode length mean | Mean policy-transition count over the most recent genuine completed episodes across target and archive origins. | steps | rollout | history | last |
 | `train/exploration/cell/unique/origin/target/rolling/mean` | Recent target unique cells mean | Mean episodic unique-cell count over recent target-origin episodes when cell-novelty shaping is active; the reset cell is included. | cells | rollout | history | last |
 | `train/progress/{progress}/origin/target/rolling/mean` | Recent target {progress} mean | Mean of a goal-declared finite numeric progress field over recent genuine target-origin episodes. | value | rollout | history | last |
+| `train/progress/{progress}/origin/target/rolling/max` | Recent target {progress} max | Maximum of a goal-declared finite numeric progress field over recent genuine target-origin episodes. | value | rollout | history | last |
 | `train/episode/completed/count` | Completed episodes | Cumulative genuine completed training episodes across origins. | episodes | rollout | history | last |
+| `train/outcome/failure/reason/{reason}/count` | Failure {reason} count | Cumulative unsuccessful completed episodes containing the reason; reason presence is counted at most once per episode. | episodes | rollout | history | last |
+| `train/outcome/failure/reason/{reason}/rolling/count` | Recent failure {reason} count | Unsuccessful completed episodes containing the reason among the most recent 100 genuine completed episodes, including warm-up before the window is full; reason presence is counted at most once per episode. | episodes | rollout | history | last |
 | `train/outcome/failure/reason/{reason}/rolling/rate` | Recent failure {reason} rate | Recent unsuccessful completed episodes containing the reason divided by all recent completed episodes; reason presence is boolean per episode. | fraction | rollout | history | last |
 | `train/outcome/success/start/{start}/episode/count` | Successful target episodes from {start} | Cumulative successful genuine target-origin episodes from one start. | episodes | rollout | history | last |
 | `train/outcome/success/start/{start}/rolling/rate` | Recent success rate from {start} | Success fraction over recent genuine target-origin attempts from one start. | fraction | rollout | history | last |
@@ -371,9 +431,11 @@ unevaluated for future explicit user action. dstack process exit alone is never
 | `train/reward/shaped/nonzero/rate` | Shaped nonzero reward rate | Fraction of learner-facing per-step rewards that are nonzero after scaling and clipping. | fraction | rollout | history | last |
 | `train/reward/raw/mean` | Raw reward mean | Mean completed task reward immediately before gradlab-owned scaling and clipping, emitted when distinct from shaped reward. | scalar | rollout | history | last |
 | `train/reward/raw/std` | Raw reward std | Standard deviation of completed task reward immediately before gradlab-owned scaling and clipping, emitted when distinct from shaped reward. | scalar | rollout | history | last |
-| `train/reward/component/{component}/mean` | Reward {component} mean | Mean active reward-component contribution in pre-transform task-reward units. | scalar | rollout | history | last |
+| `train/reward/component/{component}/mean` | Reward {component} mean | Mean configured reward-component contribution over every policy transition in the rollout, including zero-valued transitions, in pre-transform task-reward units. | scalar | rollout | history | last |
 | `train/reward/component/{component}/nonzero/rate` | Reward {component} activity rate | Fraction of active reward-component values that are nonzero. | fraction | rollout | history | last |
 | `train/reward/component/{component}/share` | Reward {component} share | Absolute contribution share computed from components in pre-transform task-reward units. | fraction | rollout | history | last |
+| `train/reward/event/{event}/mean` | Reward event {event} mean | Mean contribution from one declared event reward in pre-transform task-reward units. | scalar | rollout | history | last |
+| `train/reward/event/{event}/nonzero/rate` | Reward event {event} activity rate | Fraction of policy transitions on which one declared event reward contributes a nonzero value. | fraction | rollout | history | last |
 | `train/algorithm/ppo/update/approx_kl` | PPO approximate KL | Approximate KL divergence for the PPO update. | scalar | rollout | history | last |
 | `train/algorithm/ppo/update/clip_fraction` | PPO clip fraction | Fraction of sampled policy ratios outside PPO's clipping interval. | fraction | rollout | history | last |
 | `train/algorithm/jerk/retained/count` | JERK retained sequences | Distinct action sequences retained by JERK search. | sequences | rollout | history | last |

{gradlab-0.1.2 → gradlab-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: gradlab
-Version: 0.1.2
+Version: 0.2.2
 Summary: Generic reinforcement-learning lab for training and evaluating game agents
 License-Expression: MIT
 License-File: LICENSE
@@ -9,12 +9,18 @@ Requires-Dist: aiohttp<4,>=3.14.3
 Requires-Dist: ale-py<0.13,>=0.12
 Requires-Dist: boto3<2,>=1.34
 Requires-Dist: box2d-py==2.3.5
-Requires-Dist: breakout-turbo-env==0.5.5; sys_platform == 'darwin' and platform_machine == 'arm64'
-Requires-Dist: breakout-turbo-env==0.5.5; sys_platform == 'linux' and platform_machine == 'x86_64'
 Requires-Dist: captum<1,>=0.9
 Requires-Dist: certifi>=2026.5.20
-Requires-Dist: gradoom==0.1.0a3; sys_platform == 'darwin' and platform_machine == 'arm64'
-Requires-Dist: gradoom==0.1.0a3; sys_platform == 'linux' and platform_machine == 'x86_64'
+Requires-Dist: env-breakoutatari2600-turbo-native==0.5.11; sys_platform == 'darwin' and platform_machine == 'arm64'
+Requires-Dist: env-breakoutatari2600-turbo-native==0.5.11; sys_platform == 'linux' and platform_machine == 'x86_64'
+Requires-Dist: env-gradoom-turbo-torch==0.2.1; sys_platform == 'darwin' and platform_machine == 'arm64'
+Requires-Dist: env-gradoom-turbo-torch==0.2.1; sys_platform == 'linux' and platform_machine == 'x86_64'
+Requires-Dist: env-stableretro-turbo==1.0.1.post48; sys_platform == 'darwin' and platform_machine == 'arm64'
+Requires-Dist: env-stableretro-turbo==1.0.1.post48; sys_platform == 'linux' and platform_machine == 'x86_64'
+Requires-Dist: env-supermariobrosnes-turbo-emu==0.7.3; sys_platform == 'darwin' and platform_machine == 'arm64'
+Requires-Dist: env-supermariobrosnes-turbo-emu==0.7.3; sys_platform == 'linux' and platform_machine == 'x86_64'
+Requires-Dist: env-vizdoom-turbo==1.3.0.post30; sys_platform == 'darwin' and platform_machine == 'arm64'
+Requires-Dist: env-vizdoom-turbo==1.3.0.post30; sys_platform == 'linux' and platform_machine == 'x86_64'
 Requires-Dist: gymnasium<1.3,>=1.2
 Requires-Dist: huggingface-hub<2,>=1.0
 Requires-Dist: jinja2<4,>=3.1
@@ -28,17 +34,11 @@ Requires-Dist: pygame-ce<3,>=2.5
 Requires-Dist: pyyaml<7,>=6
 Requires-Dist: rich<16,>=15
 Requires-Dist: stable-baselines3<3,>=2.3
-Requires-Dist: stable-retro-turbo==1.0.1.post43; sys_platform == 'darwin' and platform_machine == 'arm64'
-Requires-Dist: stable-retro-turbo==1.0.1.post43; sys_platform == 'linux' and platform_machine == 'x86_64'
-Requires-Dist: supermariobrosnes-turbo==0.6.6; sys_platform == 'darwin' and platform_machine == 'arm64'
-Requires-Dist: supermariobrosnes-turbo==0.6.6; sys_platform == 'linux' and platform_machine == 'x86_64'
 Requires-Dist: tensorboard<3,>=2.16
 Requires-Dist: textual<9,>=8.2.8
 Requires-Dist: torch==2.13.0; sys_platform == 'darwin' and platform_machine == 'arm64'
 Requires-Dist: torch==2.13.0; sys_platform == 'linux' and platform_machine == 'x86_64'
 Requires-Dist: tqdm<5,>=4.67
-Requires-Dist: vizdoom-turbo==1.3.0.post26; sys_platform == 'darwin' and platform_machine == 'arm64'
-Requires-Dist: vizdoom-turbo==1.3.0.post26; sys_platform == 'linux' and platform_machine == 'x86_64'
 Requires-Dist: wandb-workspaces<0.5,>=0.4
 Requires-Dist: wandb<0.23,>=0.18
 Provides-Extra: dataset
@@ -64,7 +64,7 @@ with portable policies and evidence-backed results.
 Try the bundled ROM-free smoke recipe without cloning, credentials, or a ROM:
 
 ```bash
-uvx gradlab@0.1.2 train gradlab__bandit/ppo
+uvx gradlab@0.2.2 train gradlab__bandit/ppo
 ```
 
 The run writes a directly playable policy below `~/.config/gradlab/runs/`.
@@ -110,8 +110,9 @@ gradlab train Blackjack-v1/ppo
 
 Use `gymnasium:<environment-id>` for the qualified environment ID. These goals
 use isolated spawned lanes, explicit masked resets, native rewards, and RGB
-rendering through the same training, evaluation, publication, and playback
-workflows as other GradLab providers. Native categorical observations remain
+rendering through the same training, checkpoint-publication, and playback
+workflows as other GradLab providers. They can establish Training Success but
+cannot establish Acceptance, Promotion, or Release. Native categorical observations remain
 categorical; Blackjack uses the fixed `MultiDiscrete([32, 11, 2])` encoding
 `(player sum, dealer card, usable ace)`.
 
@@ -165,20 +166,28 @@ install -m 600 ops/operator.example.toml ~/.config/gradlab/operator.toml
 gradlab experiment operator-preflight --json
 ```
 
-Then launch a checked-in goal and recipe with a finite duration and a specific
-description:
+Then launch a checked-in recipe using its resolved goal and bounded defaults:
 
 ```bash
 gradlab experiment launch \
-  --goal-file experiments/goals/SuperMarioBros-Nes-v0/Level1-1/_goal.yaml \
   --recipe-file experiments/goals/SuperMarioBros-Nes-v0/Level1-1/recipes/ppo.yaml \
-  --seed 123 \
-  --run-description "Mario Level1-1 PPO seed 123" \
-  --compute local \
-  --max-duration 48h \
-  --json
+  --follow
 ```
 
+The recipe path identifies its owning goal. The launch seed defaults to `12`,
+the description defaults to `<goal> <recipe> seed <seed>`, compute defaults to
+the configured local fleet, and maximum duration defaults to 48 hours.
+`--follow` keeps the command attached after submission, streams authoritative
+run-state changes, and exits when training and its terminal drain are complete.
+Interrupting the client stops the stream without canceling the remote run. Omit
+the flag to retain asynchronous submission. Add `--json` for typed JSON Lines
+events (`launch`, `status`, and `terminal`).
+
+When the selected coordinator declares `ssh_tunnel` metadata in private
+`operator.toml`, this same command reuses an existing local endpoint or opens a
+temporary SSH tunnel automatically. The tunnel remains attached for the full
+command and is closed on exit only when GradLab created it.
+
 Local compute requires an enrolled fleet in
 `~/.config/gradlab/instances.md`. Paid cloud compute is always bounded and
 explicitly authorized. See [COMPUTE.md](COMPUTE.md) and the
@@ -189,9 +198,9 @@ explicitly authorized. See [COMPUTE.md](COMPUTE.md) and the
 - GradLab requires Python 3.14 and uses `uv` with a committed lockfile and a
   seven-day dependency age gate. Supported binary targets are macOS arm64 and
   Linux x86_64.
-- Local `gradlab train` runs disable W&B and checkpoint evaluation by default.
-  They are training-only and cannot establish goal acceptance or checkpoint
-  promotion.
+- Local `gradlab train` Runs disable W&B and acceptance evaluation by default.
+  They can establish Training Success but cannot establish Acceptance or
+  Promotion.
 - `gradlab.ppo` is the opt-in tensor-native PPO backend. It accepts the
   `sb3.ppo` configuration surface plus `precision` (`fp32`, `amp-fp16`, or
   `amp-bf16`) and an `execution_profile`. `sb3-parity` preserves SB3's eager,
@@ -210,9 +219,11 @@ explicitly authorized. See [COMPUTE.md](COMPUTE.md) and the
 - dstack task success is not scientific success. A queued run succeeds only
   when its terminal receipt proves checkpoint publication, evaluation drain,
   promotion state, and metric delivery.
-- [SPECS.md](SPECS.md) defines product requirements, [METRICS.md](METRICS.md)
-  defines metric semantics, and [experiments/README.md](experiments/README.md)
-  explains the checked-in research contracts.
+- [SPECS.md](SPECS.md) defines project-wide product requirements,
+  [docs/specs/](docs/specs/README.md) defines scoped product requirements,
+  [METRICS.md](METRICS.md) defines metric semantics, and
+  [experiments/README.md](experiments/README.md) explains the checked-in
+  research contracts.
 
 ## Architecture
 

{gradlab-0.1.2 → gradlab-0.2.2}/README.md

@@ -12,7 +12,7 @@ with portable policies and evidence-backed results.
 Try the bundled ROM-free smoke recipe without cloning, credentials, or a ROM:
 
 ```bash
-uvx gradlab@0.1.2 train gradlab__bandit/ppo
+uvx gradlab@0.2.2 train gradlab__bandit/ppo
 ```
 
 The run writes a directly playable policy below `~/.config/gradlab/runs/`.
@@ -58,8 +58,9 @@ gradlab train Blackjack-v1/ppo
 
 Use `gymnasium:<environment-id>` for the qualified environment ID. These goals
 use isolated spawned lanes, explicit masked resets, native rewards, and RGB
-rendering through the same training, evaluation, publication, and playback
-workflows as other GradLab providers. Native categorical observations remain
+rendering through the same training, checkpoint-publication, and playback
+workflows as other GradLab providers. They can establish Training Success but
+cannot establish Acceptance, Promotion, or Release. Native categorical observations remain
 categorical; Blackjack uses the fixed `MultiDiscrete([32, 11, 2])` encoding
 `(player sum, dealer card, usable ace)`.
 
@@ -113,20 +114,28 @@ install -m 600 ops/operator.example.toml ~/.config/gradlab/operator.toml
 gradlab experiment operator-preflight --json
 ```
 
-Then launch a checked-in goal and recipe with a finite duration and a specific
-description:
+Then launch a checked-in recipe using its resolved goal and bounded defaults:
 
 ```bash
 gradlab experiment launch \
-  --goal-file experiments/goals/SuperMarioBros-Nes-v0/Level1-1/_goal.yaml \
   --recipe-file experiments/goals/SuperMarioBros-Nes-v0/Level1-1/recipes/ppo.yaml \
-  --seed 123 \
-  --run-description "Mario Level1-1 PPO seed 123" \
-  --compute local \
-  --max-duration 48h \
-  --json
+  --follow
 ```
 
+The recipe path identifies its owning goal. The launch seed defaults to `12`,
+the description defaults to `<goal> <recipe> seed <seed>`, compute defaults to
+the configured local fleet, and maximum duration defaults to 48 hours.
+`--follow` keeps the command attached after submission, streams authoritative
+run-state changes, and exits when training and its terminal drain are complete.
+Interrupting the client stops the stream without canceling the remote run. Omit
+the flag to retain asynchronous submission. Add `--json` for typed JSON Lines
+events (`launch`, `status`, and `terminal`).
+
+When the selected coordinator declares `ssh_tunnel` metadata in private
+`operator.toml`, this same command reuses an existing local endpoint or opens a
+temporary SSH tunnel automatically. The tunnel remains attached for the full
+command and is closed on exit only when GradLab created it.
+
 Local compute requires an enrolled fleet in
 `~/.config/gradlab/instances.md`. Paid cloud compute is always bounded and
 explicitly authorized. See [COMPUTE.md](COMPUTE.md) and the
@@ -137,9 +146,9 @@ explicitly authorized. See [COMPUTE.md](COMPUTE.md) and the
 - GradLab requires Python 3.14 and uses `uv` with a committed lockfile and a
   seven-day dependency age gate. Supported binary targets are macOS arm64 and
   Linux x86_64.
-- Local `gradlab train` runs disable W&B and checkpoint evaluation by default.
-  They are training-only and cannot establish goal acceptance or checkpoint
-  promotion.
+- Local `gradlab train` Runs disable W&B and acceptance evaluation by default.
+  They can establish Training Success but cannot establish Acceptance or
+  Promotion.
 - `gradlab.ppo` is the opt-in tensor-native PPO backend. It accepts the
   `sb3.ppo` configuration surface plus `precision` (`fp32`, `amp-fp16`, or
   `amp-bf16`) and an `execution_profile`. `sb3-parity` preserves SB3's eager,
@@ -158,9 +167,11 @@ explicitly authorized. See [COMPUTE.md](COMPUTE.md) and the
 - dstack task success is not scientific success. A queued run succeeds only
   when its terminal receipt proves checkpoint publication, evaluation drain,
   promotion state, and metric delivery.
-- [SPECS.md](SPECS.md) defines product requirements, [METRICS.md](METRICS.md)
-  defines metric semantics, and [experiments/README.md](experiments/README.md)
-  explains the checked-in research contracts.
+- [SPECS.md](SPECS.md) defines project-wide product requirements,
+  [docs/specs/](docs/specs/README.md) defines scoped product requirements,
+  [METRICS.md](METRICS.md) defines metric semantics, and
+  [experiments/README.md](experiments/README.md) explains the checked-in
+  research contracts.
 
 ## Architecture
 

{gradlab-0.1.2 → gradlab-0.2.2}/experiments/goals/Breakout-Atari2600-v0/_goal.yaml

@@ -9,14 +9,18 @@ tags:
 title: Atari 2600 Breakout wall completion
 objective:
   rank:
-  - max(train/episode/return/shaped/origin/target/rolling/mean)
+  - max(train/progress/bricks_destroyed/origin/target/rolling/max)
   - min(train/global_step)
 train:
   checkpoint_freq: 500000
+  episode_progress_fields:
+  - score
+  - bricks_destroyed
+  - bricks_destroyed_normalized
   environment:
     # Breakout Turbo is the default ROM-free implementation. The complete contract is
     # intentionally accepted by Stable Retro Turbo so only env_provider needs to change.
-    env_provider: &breakout_provider breakout-turbo-env
+    env_provider: &breakout_provider env-breakoutatari2600-turbo-native
     env_config:
       <<: &breakout_env_config
         game: Breakout-Atari2600-v0
@@ -56,6 +60,16 @@ train:
       action:
         # GradLab normalizes both providers to 0=NOOP, 1=FIRE, 2=RIGHT, 3=LEFT.
         set: native
+        conditional_overrides:
+        - id: auto_serve
+          when:
+            signal: ball_y
+            operation: equals
+            value: 0
+          replace_with:
+            # Stable Retro names the Atari controller trigger BUTTON; in Breakout
+            # this is the FIRE action that launches the waiting ball.
+            semantic_id: button
       signals:
         ball_y: ball_y
         walls_cleared: walls_cleared
@@ -66,6 +80,8 @@ train:
         ball_vy: ball_vy
         # The live-state curriculum groups reachable Breakout states by score stage.
         score: score
+        bricks_destroyed: bricks_destroyed
+        bricks_destroyed_normalized: bricks_destroyed_normalized
       events:
         serve_stall:
           signal: ball_y
@@ -82,3 +98,5 @@ train:
         reward_mode: native
         reward_scale: 1.0
         reward_clip: false
+        event_rewards:
+          serve_stall: -5.0

gradlab-0.2.2/experiments/goals/Breakout-Atari2600-v0/recipes/ppo-ball-state.yaml

@@ -0,0 +1,62 @@
+defaults:
+- ../../../recipes/_presets/breakout-ball-state-ablation-ppo@_global_
+- _self_
+recipe_id: ppo-ball-state
+description: Native Breakout PPO with centered ball position, velocity, and paddle position fused after the visual encoder.
+train:
+  environment:
+    task:
+      model_inputs:
+        schema_version: 1
+        context:
+          ball_x:
+            signal: policy_ball_x
+            update: transition
+            encoding:
+              kind: continuous
+              scale: 2.0
+              offset: -1.0
+              # Provider ratios deliberately preserve off-viewport values.
+              low: null
+              high: null
+              clip: false
+          ball_y:
+            signal: policy_ball_y
+            update: transition
+            encoding:
+              kind: continuous
+              scale: 2.0
+              offset: -1.0
+              low: null
+              high: null
+              clip: false
+          ball_vx:
+            signal: policy_ball_vx
+            update: transition
+            encoding:
+              kind: continuous
+              scale: 1.0
+              offset: 0.0
+              low: null
+              high: null
+              clip: false
+          ball_vy:
+            signal: policy_ball_vy
+            update: transition
+            encoding:
+              kind: continuous
+              scale: 1.0
+              offset: 0.0
+              low: null
+              high: null
+              clip: false
+          paddle_x:
+            signal: policy_paddle_x
+            update: transition
+            encoding:
+              kind: continuous
+              scale: 2.0
+              offset: -1.0
+              low: null
+              high: null
+              clip: false

gradlab-0.2.2/experiments/goals/Breakout-Atari2600-v0/recipes/ppo-fusion-256.yaml

@@ -0,0 +1,5 @@
+defaults:
+- ../../../recipes/_presets/breakout-ball-state-ablation-ppo@_global_
+- _self_
+recipe_id: ppo-fusion-256
+description: Architecture-matched native Breakout PPO control with a 256-unit post-CNN fusion layer but no privileged state inputs.

gradlab-0.2.2/experiments/goals/Breakout-Atari2600-v0/recipes/ppo.yaml

@@ -0,0 +1,26 @@
+defaults:
+- ../../../recipes/_presets/breakout-high-throughput-ppo@_global_
+- _self_
+recipe_id: ppo
+description: High-throughput three-action PPO for {{ goal_id }} with learning-rate and entropy decay plus five-point life-loss and serve-stall penalties.
+train:
+  environment:
+    env_config:
+      env_args:
+        # Both Breakout providers compile this table to the same three-action
+        # semantic contract: BUTTON/FIRE, RIGHT, LEFT. NOOP remains available
+        # only to the reset randomizer, outside the policy action space.
+        use_restricted_actions:
+        - [BUTTON]
+        - [RIGHT]
+        - [LEFT]
+    task:
+      signals:
+        lives: lives
+      events:
+        life_loss:
+          signal: lives
+          operation: decrease
+      reward:
+        event_rewards:
+          life_loss: -5.0

{gradlab-0.1.2 → gradlab-0.2.2}/experiments/goals/SuperMarioBros-Nes-v0/_goal-family-common.yaml

@@ -32,7 +32,7 @@ train:
         action: stop
   environment:
     # SuperMarioBros-NES Turbo supplies SuperMarioBrosNesTurboVecEnv.
-    env_provider: &mario_env_provider supermariobrosnes-turbo
+    env_provider: &mario_env_provider env-supermariobrosnes-turbo-emu
     env_config:
       <<: &mario_env_config
         # Stable Retro-compatible game id passed to SuperMarioBrosNesTurboVecEnv.

{gradlab-0.1.2 → gradlab-0.2.2}/experiments/goals/VizdoomDeathmatch-v1/recipes/gradoom-ppo.yaml

@@ -5,14 +5,18 @@ recipe_id: gradoom-ppo
 description: GPU-resident GraDOOM Deathmatch PPO trained on one RTX 4090 and evaluated zero-shot in reference ViZDoom.
 reward_shape: native-v1
 train:
-  timesteps: 500000000
+  timesteps: 50000000
+  checkpoint_eval_backend: none
   environment:
-    # Training uses GraDOOM; the goal-owned checkpoint evaluator remains vizdoom-turbo.
-    env_provider: gradoom
+    # Training uses GraDOOM; the goal-owned checkpoint evaluator remains env-vizdoom-turbo.
+    env_provider: env-gradoom-turbo-torch
     env_config:
+      # GPU-resident GraDOOM scales to thousands of lanes; 2048 won the 128..4096
+      # time-to-rolling-kills sweep on beast-3 (~9.5k steps/s, best kills curve).
+      n_envs: 2048
       env_args:
-        # GraDOOM is single-stream GPU execution; this compatibility knob is intentionally inert.
-        num_threads: 1
+        # GraDOOM is single-stream GPU execution; the API expects None for device-backed execution.
+        num_threads: null
         # Keep the supported eager engine until the production CUDA graph passes its release gate.
         compile_engine: false
     preprocessing:

{gradlab-0.1.2 → gradlab-0.2.2}/experiments/goals/_vizdoom-common.yaml

@@ -75,7 +75,7 @@ train:
   # Define the provider, environment, preprocessing, and task contract used for training.
   environment:
     # Select the environment provider and anchor it for evaluation reuse.
-    env_provider: &vizdoom_provider vizdoom-turbo
+    env_provider: &vizdoom_provider env-vizdoom-turbo
     # Define provider-independent and provider-specific environment settings.
     env_config:
       # Anchor the complete base environment mapping for evaluation reuse.