Exprun
Purpose
Exprun is the execution counterpart to expgen. It consumes exp_handoff.yaml, builds a full run matrix, launches experiments, monitors progress, handles operational repair, and writes final results.
Use expgen first when the experiment repository or handoff does not exist.
State Machine
Use exprun_state.json in the chosen output directory. Resolve bundled scripts relative to this SKILL.md.
python scripts/exp_state_guard.py init --dir <output-dir>
python scripts/exp_state_guard.py enter --dir <output-dir> --stage handoff
python scripts/validate_handoff.py --file <output-dir>/exp_handoff.yaml
python scripts/exp_state_guard.py pass --dir <output-dir> --stage handoff --artifact exp_handoff.yaml
python scripts/exp_state_guard.py enter --dir <output-dir> --stage plan
python scripts/exp_state_guard.py pass --dir <output-dir> --stage plan --artifact full/matrix.yaml
python scripts/exp_state_guard.py enter --dir <output-dir> --stage run
python scripts/exp_state_guard.py pass --dir <output-dir> --stage run --artifact full/run_monitors.jsonl --artifact full/monitoring_summary.json
python scripts/exp_state_guard.py enter --dir <output-dir> --stage report
python scripts/exp_state_guard.py pass --dir <output-dir> --stage report --artifact full/final_report.md
Legal order:
handoff -> plan -> run -> report
Hard rules:
- If the handoff is invalid, block before planning.
- Do not change the research claim, metric direction, or validated protocol from
exp_handoff.yaml.
- Repair only operational failures: transient infra, resumable job failure, output collection, or log aggregation.
- Block on semantic drift, repeated deterministic failure, budget overrun, or missing raw outputs.
- Subagents may inspect logs or propose repairs, but only the orchestrator calls the state guard.
Dispatcher
Use scripts/dispatch_node.py to identify the current stage and reference file:
python scripts/dispatch_node.py --dir <output-dir>
The dispatcher is advisory routing; exp_state_guard.py is authoritative state control.
Workflow
- Validate
exp_handoff.yaml.
- Freeze repository/config snapshot.
- Build
full/matrix.yaml across variants, seeds, scales, and repeats.
- Launch runs with stable per-run output directories.
- Monitor every interval
t; default t is 30 minutes for long runs.
- Record command, PID/job id, status, metrics path, artifact integrity, budget, and next action.
- Repair only operational failures and record repair evidence.
- Write
full/final_report.md.
Required Artifacts
Handoff pass requires:
Plan pass requires:
Run pass requires:
full/run_monitors.jsonlfull/monitoring_summary.json
Report pass requires:
Output
Exprun should produce:
exprun_state.jsonevents.jsonlfull/matrix.yamlfull/run_monitors.jsonlfull/monitoring_summary.jsonfull/final_report.md- optional
experiment_results.yaml
1---2name: exprun3description: Use when expgen has produced an experiment handoff and the task is to execute, monitor, repair operational failures, and report full experiments.4---56# Exprun78## Purpose910Exprun is the execution counterpart to `expgen`. It consumes `exp_handoff.yaml`, builds a full run matrix, launches experiments, monitors progress, handles operational repair, and writes final results.1112Use `expgen` first when the experiment repository or handoff does not exist.1314## State Machine1516Use `exprun_state.json` in the chosen output directory. Resolve bundled scripts relative to this `SKILL.md`.1718```bash19python scripts/exp_state_guard.py init --dir <output-dir>20python scripts/exp_state_guard.py enter --dir <output-dir> --stage handoff21python scripts/validate_handoff.py --file <output-dir>/exp_handoff.yaml22python scripts/exp_state_guard.py pass --dir <output-dir> --stage handoff --artifact exp_handoff.yaml23python scripts/exp_state_guard.py enter --dir <output-dir> --stage plan24python scripts/exp_state_guard.py pass --dir <output-dir> --stage plan --artifact full/matrix.yaml25python scripts/exp_state_guard.py enter --dir <output-dir> --stage run26python scripts/exp_state_guard.py pass --dir <output-dir> --stage run --artifact full/run_monitors.jsonl --artifact full/monitoring_summary.json27python scripts/exp_state_guard.py enter --dir <output-dir> --stage report28python scripts/exp_state_guard.py pass --dir <output-dir> --stage report --artifact full/final_report.md29```3031Legal order:3233```text34handoff -> plan -> run -> report35```3637Hard rules:3839- If the handoff is invalid, block before planning.40- Do not change the research claim, metric direction, or validated protocol from `exp_handoff.yaml`.41- Repair only operational failures: transient infra, resumable job failure, output collection, or log aggregation.42- Block on semantic drift, repeated deterministic failure, budget overrun, or missing raw outputs.43- Subagents may inspect logs or propose repairs, but only the orchestrator calls the state guard.4445## Dispatcher4647Use `scripts/dispatch_node.py` to identify the current stage and reference file:4849```bash50python scripts/dispatch_node.py --dir <output-dir>51```5253The dispatcher is advisory routing; `exp_state_guard.py` is authoritative state control.5455## Workflow56571. Validate `exp_handoff.yaml`.582. Freeze repository/config snapshot.593. Build `full/matrix.yaml` across variants, seeds, scales, and repeats.604. Launch runs with stable per-run output directories.615. Monitor every interval `t`; default `t` is 30 minutes for long runs.626. Record command, PID/job id, status, metrics path, artifact integrity, budget, and next action.637. Repair only operational failures and record repair evidence.648. Write `full/final_report.md`.6566## Required Artifacts6768Handoff pass requires:6970- `exp_handoff.yaml`7172Plan pass requires:7374- `full/matrix.yaml`7576Run pass requires:7778- `full/run_monitors.jsonl`79- `full/monitoring_summary.json`8081Report pass requires:8283- `full/final_report.md`8485## Output8687Exprun should produce:8889- `exprun_state.json`90- `events.jsonl`91- `full/matrix.yaml`92- `full/run_monitors.jsonl`93- `full/monitoring_summary.json`94- `full/final_report.md`95- optional `experiment_results.yaml`
opendcai