AI trainer support: refactor, infrastructure, and one desync fix

.github/workflows/build.yml

@@ -46,6 +46,10 @@ jobs:
         run: |
           scons -j$(nproc)
           ./TestsRunner
+          for harness in ./*Harness ./*Test; do
+            echo "== $harness"
+            "$harness"
+          done
 
   windows:
     name: windows (mingw-w64)

.gitignore

@@ -3,6 +3,7 @@ options_cache.py
 libgag.a
 libusl.a
 src/glob2
+testResults.xml
 .sconf_temp
 .sconsign.dblite
 *.o
@@ -12,3 +13,9 @@ src/glob2
 __pycache__/
 build/
 vcpkg_installed/
+.DS_Store
+compile_commands.json
+.cache/
+Glob2.app/
+Glob2-*.dmg
+/.tmp

CLAUDE.md

@@ -1,108 +1,81 @@
-# glob2 (Legacy C++ Codebase)
+# glob2 (C++ Codebase)
 
-This is the original Globulation 2 C++ codebase. It is legacy code and is not under active development.
+The Globulation 2 C++ codebase. Actively maintained.
 
-## Build Commands
+## Build
 
 ```bash
-cd glob2
-
-# Build (requires SCons, Python 3)
-scons -j16
+scons -j16                 # default: -g, no -O
+scons release=1 -j16       # optimized; use for any headless/replay work
+scons server=1             # YOG server only (no GUI/sound)
+scons -c                   # clean
+scons --build=/tmp/out     # out-of-source
+scons mingw=1              # native Windows (MSYS2/mingw-w64)
+scons mingwcross=1         # cross-compile for Windows from Linux
+scons BINDIR=/path/bin INSTALLDIR=/path/share
+```
 
-# Install (may need root)
-scons install
+Options are cached in `options_cache.py`, so `release=1` and `server=1` stick until you pass `release=0` / `server=0`.
 
-# Clean
-scons -c
+**Server build gotcha.** Always build the server with `scons server=1`, never a bare `scons build/src/glob2-server`. The flag defines `YOG_SERVER_ONLY` and switches to the stripped `libgag_server.a`. Without it the objects are compiled with GUI code but linked against the stripped library, producing dozens of misleading undefined-symbol errors.
 
-# Build options
-scons release=1          # Optimized release build
-scons server=1           # Build YOG server only (no GUI/sound)
-scons --build=/tmp/out   # Out-of-source build
-scons mingw=1            # Native Windows build (MSYS2/mingw-w64)
-scons mingwcross=1       # Cross-compile for Windows from Linux
+**Use `release=1` for headless runs.** The default build is roughly 10× slower under `--nox` / `-test-games-nox`. Drop back to the default only when you need a debugger, sanitizers, or fast incremental rebuilds.
 
-# Custom paths
-scons BINDIR=/path/bin INSTALLDIR=/path/share
-```
+**`DET_INIT` — hunting uninitialized-read nondeterminism.** Valgrind/MSan don't work on modern macOS. Instead build twice, `DET_INIT=zero scons` and `DET_INIT=pattern scons`, and hammer one seed serially per build (add `MallocPreScribble=1 MallocScribble=1` to scribble the heap). If each build is internally stable but the two disagree, an uninitialized stack read is confirmed; if a scribbled build is still unstable run-to-run, the cause is not uninitialized memory. The env var is invisible to scons's dependency tracking, so rebuild affected objects when toggling.
 
-**Dependencies:** SDL2, SDL2_net, SDL2_ttf, SDL2_image, libvorbis, libogg, speex, OpenGL, GLU, libepoxy, Boost (date_time; system is header-only from 1.69 on and only linked when present), zlib, fribidi, pcre. Optional: portaudio (voice chat). See `vcpkg.json` for the full list.
+**Dependencies:** SDL2, SDL2_net, SDL2_ttf, SDL2_image, libvorbis, libogg, speex, OpenGL, GLU, libepoxy, Boost date_time, zlib, fribidi, pcre. Optional: portaudio. See `vcpkg.json`.
 
-## Running Tests
+## Tests
 
-Tests have their own `test/SConstruct` and are **not** built by the top-level `scons`:
+Tests live in `test/` with their own `test/SConstruct` and are **not** built by the top-level `scons`:
 
 ```bash
 cd test
 scons -j16
 ./TestsRunner
+./WinningConditionsHarness
 ```
 
-## Build System Internals
+Binaries are written in-tree. A top-level `scons` reports "up to date" without touching them, so a stale binary keeps passing against changed assertions. Rebuild from `test/` before trusting a run.
 
-SCons-based. `SConstruct` is the main build script with platform detection (Linux, Darwin, Windows/MinGW). Library checks are done via custom configure functions in `scons/`. Build options are cached in `options_cache.py`.
-
-## Architecture
+See [`test/README.md`](test/README.md) for the Map subclass pattern used to unit-test Map predicates without pulling in `globalContainer`, `Team`, or the full simulation.
 
-### Engine Loop (40ms tick)
+## Headless Runs and Replays
 
-The engine is **synchronous** — no multithreading in the core. Every 40ms, `Engine::run()` calls `.step()` on the class hierarchy. See `doc/sourceCodeUnderstanding.txt` for the full explanation.
+See [docs/headless-replays.md](docs/headless-replays.md).
 
-```
-Engine::run() loop:
-  gui.step()                    → handle input
-  net.pushOrder(gui.getOrder()) → send local player order to network
-  net.pushOrder(ai.getOrder())  → send AI orders
-  net.step()                    → exchange orders over network
-  gui.executeOrder(...)         → execute all received orders
-  gui.drawAll()                 → render
-  sleep()                       → maintain 40ms frame
+```bash
+./glob2 -test-games-nox                      # random AI-vs-AI games, loops forever
+./glob2 --nox <game-file> <steps> <runs>     # single game from a .game file
 ```
 
-### Class Hierarchy
+Replays go to `~/.glob2/replays/last_game.replay` unless `GLOB2_REPLAY_PATH` is set. The lockstep engine is the regression test: identical replays mean identical behavior. See [`../docs/replay-verification.md`](../docs/replay-verification.md).
 
-```
-Engine
-├─ NetGame          (network abstraction, order transmission via UDP)
-└─ GameGUI          (rendering, input)
-   └─ Game          (game state)
-      ├─ Map        (terrain, resources)
-      ├─ Team[32]   (a "colony" — has color, units, buildings)
-      │  ├─ Unit[1024]
-      │  └─ Building[1024]
-      ├─ Player[32] (human interface — keyboard+mouse or AI)
-      └─ Session    (serializable state: BasePlayer[32], BaseTeam[32])
-```
+## Architecture
+
+The engine is synchronous, one 40ms tick at a time, and every client computes identical state from the same stream of `Order`s. `doc/sourceCodeUnderstanding.txt` has the full walkthrough. Two things to hold onto:
+
+- **Team vs Player.** A Team is a colony (color, units, buildings). A Player is a controller, human or AI. Several players may control one team; only teams can be allied.
+- **Determinism.** Use `Utilities::syncRand()`, never `rand()`. Avoid `std::set`; iteration order is not portable.
 
-**Team vs Player:** A Team is a logical colony (color, units, buildings). A Player is a controller (human or AI). Multiple players can control one team. Only teams can be allied.
+AI implementations live under `src/ai/`: Castor, Cortex, Echo, Nicowar, Numbi, Warrush, all behind `AIImplementation`.
 
-### Deterministic Networking
+## Conventions
 
-All clients compute identical game state. Only Orders (player actions) are transmitted. This requires:
-- **Use `Utilities::syncRand()`** instead of `rand()` — all machines must get the same random numbers
-- **Avoid `std::set`** — it is non-deterministic across platforms
-- Orders are buffered in per-player FIFO queues (256 slots) to handle latency
+**Filenames:** PascalCase (`Game.cpp`, `GameRenderUnits.cpp`). Do not introduce snake_case C++ filenames. On macOS a case-only rename needs `git mv -f Foo.cpp foo_tmp.cpp && git mv -f foo_tmp.cpp Foo.cpp`; a direct rename may silently no-op.
 
-### Key Source Directories
+**Header guards:** `#pragma once`.
 
-- **`src/`** — Main game (382 files): engine, game logic, AI, networking, GUI screens, YOG online system
-- **`libgag/`** — Graphics/GUI toolkit library (widget system, sprites, file I/O, rendering)
-- **`libusl/`** — USL scripting language for maps/campaigns
-- **`libwee/`** — Utility library
-- **`data/`** — Runtime assets (graphics, fonts, music, GUI resources)
-- **`maps/`** — Game maps
-- **`campaigns/`** — Campaign definitions
-- **`doc/`** — Architecture documentation
+**Unused includes:** run `tools/remove-unused-includes.py` after `scons compile_commands.json`. Never hand-guess or run `clang-tidy --fix` blindly. Afterwards rebuild both `scons` and `scons server=1` and verify with Workflow 1 in the replay-verification doc.
 
-### AI System
+**Comments:** match the surrounding terse style. The *why* of a change goes in the commit message. Add a comment only when the code can't carry the reasoning itself.
 
-Multiple AI implementations in `src/`: AICastor, AIEcho, AINicowar, AINumbi, AIToubib, AIWarrush — all inherit from `AI` base class.
+**Never document the past.** How code used to look, why it changed, or where something "used to live" belongs in the commit message only. When you remove something, remove it completely: no tombstone comments, no "moved to X" pointers. Describe only what the code does now. The same applies to replies: don't recount the history of a change unless asked.
 
-### Orders System
+## Logging
 
-All player actions are serialized as `Order` objects (see `src/Order.h`). `NullOrder` means "player did nothing this tick" — distinct from "we haven't heard from this player yet." Orders carry complete action data (team, position, type, unit counts).
+There is no logging facility; diagnostics go to `std::cerr`. Do not propose adding a logging library; nothing consumes the data.
 
-### YOG (Online Gaming)
+## Pathfinding: chamfer pass cap
 
-Server/client architecture for online play. `YOGServer` handles matchmaking, chat channels, ratings, map database. LAN play is peer-to-peer. Build server-only binary with `scons server=1`.
+In `src/map/gradient/MapGradientGlobal.cpp` the chamfer distance transform's convergence-pass cap is bounded by the Uint8 value range (256), not by the Borgefors 1-pass result. Borgefors holds only on an obstacle-free grid; with obstacles each bend in the propagation path costs about K/2 passes, and real 128×128 maps needed well over 8. The cap is a tripwire for monotonicity violations, not a throttle. Do not derive a tighter bound from grid geometry.

SConstruct

@@ -156,6 +156,8 @@ def configure(env, server_only):
         if isDarwinPlatform:
             print("Using Apple's OpenGL framework")
             env.Append(FRAMEWORKS=["OpenGL", "CoreFoundation"])
+            # Silence Apple's hundreds of OpenGL deprecation warnings.
+            env.Append(CPPDEFINES=["GL_SILENCE_DEPRECATION"])
         elif conf.CheckLib("GL") and conf.CheckCXXHeader("GL/gl.h"):
             gl_libraries.append("GL")
         elif conf.CheckLib("GL") and conf.CheckCXXHeader("OpenGL/gl.h"):
@@ -243,11 +245,22 @@ def main():
               default='build',
               help='build directory')
     env = Environment()
+    # SCons scrubs the shell environment for build commands; without TMPDIR,
+    # tools like ar fall back to /tmp, which sandboxed environments may block.
+    if 'TMPDIR' in os.environ:
+        env['ENV']['TMPDIR'] = os.environ['TMPDIR']
     env["VERSION"] = "0.9.5.0"
     establish_options(env)
 
+    # Emit compile_commands.json for clangd / IDE LSPs.
+    env.Tool('compilation_db')
+    env.CompilationDatabase()
+
     if env['mingw'] or env['mingwcross']:
         Tool('mingw')(env)
+    if env['mingw'] or isWindowsPlatform:
+        # Windows caps command lines at 32K; pass the link arguments via @response-file
+        env['LINKCOM'] = '${TEMPFILE("$LINK -o $TARGET $LINKFLAGS $__RPATH $SOURCES $_LIBDIRFLAGS $_LIBFLAGS", "$LINKCOMSTR")}'
 
     if env['mingwcross']:
             env.Platform('cygwin')
@@ -291,8 +304,22 @@ def main():
 
     env.Append(CPPPATH=['#libgag/include', '#'])
     env.Append(CPPPATH=['#libusl/src', '#'])
-    env.Append(CPPPATH=['#src'])
-    env.Append(CXXFLAGS=' -Wall -fPIC')
+    env.Append(CPPPATH=['#src', '#src/yog', '#src/ai', '#src/building',
+                        '#src/game/entities',
+                        '#src/gui',
+                        '#src/map', '#src/map/edit', '#src/map/generator',
+                        '#src/map/gradient', '#src/map/io', '#src/map/pathfind',
+                        '#src/net', '#src/net/irc', '#src/net/message',
+                        '#src/sgsl',
+                        '#src/team',
+                        '#src/unit'])
+    env.Append(CXXFLAGS=' -std=gnu++20 -Wall -fPIC')
+    # Uninitialized-read diagnostics: DET_INIT=zero|pattern forces deterministic
+    # stack initialization (see CLAUDE.md). Env var, not a cached scons option.
+    _detinit = os.environ.get('DET_INIT')
+    if _detinit:
+        env.Append(CXXFLAGS=' -ftrivial-auto-var-init=' + _detinit)
+        env.Append(CCFLAGS=' -ftrivial-auto-var-init=' + _detinit)
     env.Append(LINKFLAGS=' -Wall')
     env.Append(LIBS=['SDL2_net'])
     if not server_only: