--seed: shuffle the order connections are routed in

The router is deterministic, but its result depends heavily on which
connection routes first. A seed shuffles that order reproducibly, so a
change can be judged over several orders instead of the one it happened
to get.

src/freeroute/cli.py

@@ -29,8 +29,8 @@ from freeroute.ses import write_ses
 #: which optional flags each engine actually implements. Anything not listed for
 #: an engine is rejected by :func:`_validate` rather than quietly ignored.
 ENGINE_OPTIONS: dict[str, frozenset[str]] = {
-    "grid": frozenset({"rip_up", "max_passes"}),
-    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes"}),
+    "grid": frozenset({"rip_up", "max_passes", "seed"}),
+    "exact": frozenset({"shove", "diagonal", "rip_up", "max_passes", "seed"}),
     "room": frozenset({"shove", "pack"}),
 }
 
@@ -41,6 +41,7 @@ _FLAG_NAMES = {
     "diagonal": "--diagonal",
     "rip_up": "--no-rip-up",
     "max_passes": "-mp/--max-passes",
+    "seed": "--seed",
 }
 
 
@@ -133,6 +134,13 @@ def build_parser() -> argparse.ArgumentParser:
         help="copper to board-edge clearance in mm, e.g. KiCad's min_copper_edge_clearance "
         "(the DSN does not carry it); default 0: copper only has to stay inside the outline",
     )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        metavar="N",
+        help="grid and exact engines: shuffle the order connections are routed in; "
+        "the same seed gives the same result (default: fewer-pin nets first)",
+    )
     return parser
 
 
@@ -152,6 +160,7 @@ def main(argv: list[str] | None = None) -> int:
             ("diagonal", args.diagonal),
             ("rip_up", args.no_rip_up),
             ("max_passes", args.max_passes is not None),
+            ("seed", args.seed is not None),
         )
         if asked
     ]
@@ -184,6 +193,7 @@ def main(argv: list[str] | None = None) -> int:
             edge_clearance_mm=args.edge_clearance,
             resolution=2 if args.grid_resolution is None else args.grid_resolution,
             heuristic_weight=args.heuristic_weight,
+            seed=args.seed,
         )
     elif args.engine == "room":
         result = build_rooms_routing_result(
@@ -195,6 +205,7 @@ def main(argv: list[str] | None = None) -> int:
             dsn, layers=layers, rip_up=rip_up, max_passes=max_passes,
             edge_clearance_mm=args.edge_clearance,
             resolution=1 if args.grid_resolution is None else args.grid_resolution,
+            seed=args.seed,
         )
 
     ses_text = write_ses(dsn, result)