Improve CC:Ladder: rung framing, richer commit labels, branch carry-over fix

Author: john-b-yang

codeclash/agents/player.py

@@ -78,12 +78,23 @@ def __init__(
                     logger=self.logger,
                 )
             else:
-                # Resume the branch if a previous round pushed it to the remote, else create it.
+                # Resume the branch if a previous rung/round pushed it to the remote, else create it.
+                # Reset the local branch to the fetched remote tip with -B.
                 assert_zero_exit_code(self.environment.execute("git fetch origin"), logger=self.logger)
-                if self.environment.execute(f"git checkout {self._branch_name}").get("returncode", 0) != 0:
-                    self.logger.info(f"Branch {self._branch_name} doesn't exist, creating it")
+                if (
+                    self.environment.execute(f"git rev-parse --verify --quiet origin/{self._branch_name}").get(
+                        "returncode", 1
+                    )
+                    == 0
+                ):
                     assert_zero_exit_code(
-                        self.environment.execute(f"git checkout -b {self._branch_name}"),
+                        self.environment.execute(f"git checkout -B {self._branch_name} origin/{self._branch_name}"),
+                        logger=self.logger,
+                    )
+                else:
+                    self.logger.info(f"Branch {self._branch_name} doesn't exist on remote, creating it")
+                    assert_zero_exit_code(
+                        self.environment.execute(f"git checkout -B {self._branch_name}"),
                         logger=self.logger,
                     )
 
@@ -172,11 +183,17 @@ def reset_and_apply_patch(self, patch: str, *, base_commit: str = "", filter_pat
 
     # --- Helper methods ---
 
+    def _round_message(self, round: int) -> str:
+        """Commit/tag message for a round. The tournament sets ``commit_label`` on the player config —
+        a prefix that carries its own separator (the ladder sets ``"Rung 2/50 (opponent, elo #49) — "``;
+        PvP sets ``""``). Pure concatenation, no per-mode branching here."""
+        return f"{self.config['commit_label']}Round {round} Update"
+
     def _tag_round(self, round: int) -> None:
         """Git tag the codebase at the given round."""
         tag = self._get_round_tag_name(round)
         assert_zero_exit_code(
-            self.environment.execute(f"git tag -a {tag} -m 'Round {round} Update'"),
+            self.environment.execute(f"git tag -a {tag} -m '{self._round_message(round)}'"),
             logger=self.logger,
         )
         self._metadata["round_tags"][round] = tag
@@ -203,7 +220,7 @@ def _commit(self) -> None:
         for cmd in [
             "git add -A",
             unstage_binaries,
-            f"git commit --allow-empty -m 'Round {r} Update'",
+            f"git commit --allow-empty -m '{self._round_message(r)}'",
         ]:
             assert_zero_exit_code(self.environment.execute(cmd), logger=self.logger)
         self._tag_round(r)

codeclash/replay/base.py

@@ -367,8 +367,7 @@ def build_index(tour: TournamentInfo) -> str:
         group_td = f"<td>{g.group}</td>" if laddered else ""
         sim_td = f"<td>{sim_winner}</td>" if have_sim_winner else ""
         rows.append(
-            f"<tr>{group_td}<td>{g.round}</td><td>{g.sim}</td>{sim_td}"
-            f"<td>{round_winner or ''}</td><td>{cell}</td></tr>"
+            f"<tr>{group_td}<td>{g.round}</td><td>{g.sim}</td>{sim_td}<td>{round_winner or ''}</td><td>{cell}</td></tr>"
         )
 
     style = (

codeclash/tournaments/ladder.py

@@ -201,13 +201,20 @@ def run(self) -> dict:
         print(advancement_rule)
         logger.info(advancement_rule)
 
-        rungs_cleared = 0
         advanced = False
         opponent: dict = {}
         opponent_rank = 0
+        rung = 0
+        total = len(self.ladder)
         for idx, opponent in enumerate(self.ladder):
-            opponent_rank = len(self.ladder) - idx
+            # `rung` counts the climb from the bottom (1 = weakest opponent faced first, `total` =
+            # strongest); `opponent_rank` is the opponent's Elo standing (1 = strongest overall).
+            rung = idx + 1
+            opponent_rank = total - idx
             opponent["name"] = _player_slug(opponent["branch_init"])
+            # Prefix the climber's commit/tag messages with rung context (a prefix carrying its own
+            # trailing separator; see Player._round_message).
+            self.player["commit_label"] = f"Rung {rung}/{total} ({opponent['name']}, elo #{opponent_rank}) — "
             if "branch_init" in self.player and idx > 0:
                 # After first opponent, remove branch_init so the player continues from the
                 # previous tournament's codebase.
@@ -256,23 +263,23 @@ def run(self) -> dict:
                 print("=" * 10)
                 print(
                     f"{self.player['name']} did not clear {opponent['name']} "
-                    f"(rank {opponent_rank}/{len(self.ladder)}): won {player_wins}/{len(round_winners)} agent rounds "
+                    f"(rung {rung}/{total}, elo #{opponent_rank}): won {player_wins}/{len(round_winners)} agent rounds "
                     f"(needed >= {self.min_round_wins}), last {self.win_last_k} round(s) won: {won_last_k}.\n"
                     "Ladder challenge ends."
                 )
                 print("=" * 10)
                 break
 
-            rungs_cleared += 1
             print("=" * 10)
             print(
-                f"{self.player['name']} successfully beat {opponent['name']} (rank {opponent_rank}/{len(self.ladder)}) "
+                f"{self.player['name']} successfully beat {opponent['name']} (rung {rung}/{total}, elo #{opponent_rank}) "
                 f"in {player_wins}/{len(round_winners)} rounds.\n"
                 "Ladder challenge continuing"
             )
             print("=" * 10)
 
         # Persist the overall climb result to a ladder-level metadata.json in the run's parent dir.
+        rungs_cleared = rung if advanced else max(rung - 1, 0)
         ladder_summary = {
             "player": self.player["name"],
             "game": self.config["game"]["name"],
@@ -290,5 +297,5 @@ def run(self) -> dict:
             json.dump(ladder_summary, f, indent=2)
 
         print(f"Ladder tournament complete. Logs saved to {self.parent_dir}")
-        print(f"Final opponent faced: {opponent['name']} (rank {opponent_rank}/{len(self.ladder)} in ladder)")
+        print(f"Final opponent faced: {opponent['name']} (rung {rung}/{total}, elo #{opponent_rank})")
         return ladder_summary

codeclash/tournaments/pvp.py

@@ -67,6 +67,9 @@ def get_metadata(self) -> dict:
 
     def get_agent(self, agent_config: dict, prompts: dict) -> Player:
         """Create an agent with environment and game context."""
+        # Commit/tag messages are prefixed with `commit_label` (see Player._round_message). PvP uses
+        # no prefix by default, but it can be overridden in the agent config.
+        agent_config.setdefault("commit_label", "")
         environment = self.game.get_environment(f"{self.game.game_id}.{agent_config['name']}")
 
         game_context = GameContext(

docs/usage/tournaments.md

@@ -19,7 +19,6 @@ uv run codeclash run <config_path> [options]
 | Flag | Short | Description |
 |------|-------|-------------|
 | `--cleanup` | `-c` | Clean up game environment after running |
-| `--push` | `-p` | Push each agent's final codebase to a new GitHub repository |
 | `--output-dir PATH` | `-o PATH` | Custom output directory (default: `logs/<username>/`) |
 | `--suffix TEXT` | `-s TEXT` | Suffix to append to the output folder name |
 | `--keep-containers` | `-k` | Keep Docker containers after games/agents finish (useful for debugging) |
@@ -37,9 +36,6 @@ uv run codeclash run configs/test/battlesnake.yaml -k
 uv run codeclash run configs/pvp/BattleSnake__claude-sonnet-4-5-20250929__o3__r15__s1000.yaml \
     -o ./my_experiments \
     -s experiment1
-
-# Push final codebases to GitHub
-uv run codeclash run configs/pvp/BattleSnake__claude-sonnet-4-5-20250929__o3__r15__s1000.yaml -p
 ```
 
 ## Configuration Anatomy
@@ -151,6 +147,22 @@ Each player entry defines an AI agent:
 | `config` | dict | Agent-specific configuration |
 | `config.model` | dict | LLM model settings |
 | `config.agent` | dict | Agent behavior settings |
+| `branch_init` | string | Optional. Git branch to seed the agent's codebase from (e.g. `human/<author>/<bot>`). Defaults to the arena's starter branch. |
+| `push` | bool | Optional (default `false`). Push the agent's evolving codebase to a remote branch after each round. Requires `GITHUB_TOKEN` with write access to the arena repo. Set per-player in the config (there is no CLI flag for it). |
+| `branch` | string | Optional. Remote branch name to push to. Usually set automatically by the orchestrator (the ladder derives it from the run); defaults to `<game_id>.<name>`. |
+| `commit_label` | string | Optional. Prefix prepended to each round's git commit/tag message (otherwise just `Round N Update`). See note below. |
+
+#### Commit labels
+
+Every round, an agent's codebase is committed (and, with `push: true`, pushed) with the message `Round N Update`. The optional `commit_label` field prepends context to that message — it's a **prefix string that carries its own separator**, so the final message is simply `f"{commit_label}Round N Update"`.
+
+It's normally set **programmatically by the tournament**, not hand-written: a plain PvP run leaves it `""` (→ `Round 1 Update`), while a **ladder** run sets it per rung so history reads like:
+
+```
+Rung 2/50 (nessegrev-julia, elo #49) — Round 1 Update
+```
+
+You *can* set it per-player in the config (e.g. to tag an experiment), but most users won't need to. Leave it unset for the default `Round N Update`.
 
 #### Model Configuration