Add an AI bench for Odyssey, and a measured review of the opponent

The engine suite guards invariants (determinism, purity, "a skirmish resolves
to a winner") and says nothing about AI QUALITY, which in a play-forever mode
is a curve over 40+ minutes rather than an assertion. So several real defects
were sitting in a fully green suite.

tools/ailab.js is a headless bench: it runs the real sim (a 40-sim-minute world
costs ~7s), drives the player side with scripted sparring bots, samples an
AI-quality metric set, and prints a scoreboard plus a named-defect list.
Subcommands: probe / sweep / compare / search / check.

The key seam is that ARCHETYPES, STRATEGIES and DIFFICULTY_OPTIONS are plain
exported tables read through defensive `|| 1` accessors, so a candidate AI is
JSON injected via --overrides, not an engine patch — the search space is already
a data document. Nothing under engine/ changed here.

docs/odyssey-ai-review.md carries the review and the tuning loop, with a
reproduction command per finding. A full-roster soak (11 worlds x 4 strategies,
40 sim-minutes, 44 runs) scores mean 0.328 and fires every detector:
production-stall 43/44, hoarding 23/44, hostile-but-idle 22/44, dev-flatline
19/44, supply-deadlock 5/44. Headline findings:

- Half a galaxy's neighbours can never attack. economic and matching both
carry neverInitiates, and neighbourAiProfile samples strategies uniformly:
0 waves in all 22 such runs while hostility sat at maximum.
- A permanent supply deadlock. The mix cycle retries one entry until it
succeeds, but the Habitat trigger fires at `used >= cap - 2` — a margin
sized for a 2-supply unit, while the Odyssey roster has 4- and 8-supply
ones. Measured on kybernet: army frozen at 66 from minute 40 to 60, both
Barracks queues empty, ore climbing past 30,000.
- The build order terminates, in a mode that doesn't.
- The Rusher never develops (9 of 12 runs at dev 1 after 40 minutes); its
Hard-only graduation lands ~30 minutes late because production runs before
industry and holds no ore reserve.
- A wiped neighbour can never re-found, so a background world dies for good.

.claude/skills/ai-lab/SKILL.md packages the loop — baseline, one hypothesis,
sweep, compare per-configuration deltas, then npm test + ailab check as
guardrails — along with the composition traps specific to this codebase.

test/ailab.test.js guards the bench itself: runs must be deterministic (or a
"+0.04 improvement" is noise) and the override seam must actually reach the sim
(or every search measures the baseline against itself). Full suite green at
1172 tests; typecheck clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V6aK9g6A9dYtyinJSVXHqQ

.claude/skills/ai-lab/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ai-lab
+description: Search for and test better Odyssey AI strategies using tools/ailab.js. Use when asked to tune, improve, evaluate, or compare the AI opponent — its archetypes (engine/aiArchetypes.js), strategies (engine/aiStrategy.js), or difficulty dials (engine/aiDifficulty.js) — or when asked why the AI in Odyssey feels passive, stalls, hoards, or plays the same on every world.
+---
+
+# Tuning the Odyssey AI
+
+`tools/ailab.js` is a headless bench: it runs the real sim for 30–60 sim-minutes per world
+(a few seconds of wall clock each), samples AI-quality metrics, and prints a scoreboard.
+Use it instead of reasoning about the AI from source — the AI's behaviour is three data
+tables composed multiplicatively across a 40-minute curve, and reading the code will not
+tell you what that curve does.
+
+## The one thing that makes this cheap
+
+A candidate AI is **JSON, not a patch**. `ARCHETYPES`, `STRATEGIES` and `DIFFICULTY_OPTIONS`
+are plain exported objects read through `|| 1`-style accessors, so `--overrides` writes new
+rows into them before a run. Explore the whole space without touching `engine/`.
+
+```json
+{
+  "strategies":   { "swarm":  { "armyAttackSizeMult": 0.5, "garrisonMult": 0.2 } },
+  "archetypes":   { "rusher": { "odyssey": { "workerTarget": 9, "expandWhenNodesBelow": 0.45 } } },
+  "difficulties": { "hard":   { "workerTargetMult": 1.4 } }
+}
+```
+
+Only promote a winner into `engine/` **after** it survives a multi-seed sweep on the full roster.
+
+## The loop
+
+1. **Baseline.** `node tools/ailab.js sweep --seeds 2 --json /tmp/base.json`
+   Never skip this. The objective is noisy and the roster is uneven; a candidate compared
+   against remembered numbers is a candidate compared against nothing.
+2. **Read the components, not the total.** Every row prints `develop / keepGrowing /
+   pressure / thrift / liveness / survive`. A total that moved without a component moving is
+   noise. Name which component you intend to move before you change anything.
+3. **One hypothesis at a time**, written as an overrides file. Two dials at once and you
+   cannot attribute the result.
+4. **Measure.** `node tools/ailab.js sweep --overrides cand.json --seeds 2 --json /tmp/cand.json`
+   then `node tools/ailab.js compare --baseline /tmp/base.json --candidate /tmp/cand.json`.
+   `compare` prints per-configuration deltas — read them. A mean that improved because one
+   world improved a lot and three got worse is a regression wearing a disguise.
+5. **Guardrails before you believe it** (all three, every time):
+   - `npm test` — determinism, engine purity, and "a skirmish resolves to a winner" on all
+     nine worlds. AI changes break the resolve guarantee more often than anything else.
+   - `node tools/ailab.js check` — the named defect list. It must not grow.
+   - Confirm the skirmish path is untouched if you only meant to change Odyssey (Odyssey-only
+     behaviour lives behind `state.diplomacy` / `state.endless` guards).
+6. **Record the result in the ledger** (`docs/odyssey-ai-review.md`, "Search ledger"), including
+   the failures. An unrecorded negative result gets re-run by the next session.
+
+## Picking the objective before you optimise
+
+`WEIGHTS` in `tools/ailab.js` encodes what "better AI" means and is deliberately editable.
+Odyssey is a **play-forever sandbox with no win condition**, so the default weights reward a
+neighbour that keeps developing, keeps spending, and applies pressure proportional to how
+hostile it has actually become — not one that wins fast. If the user wants something else
+(a harder opponent, a more passive galaxy), change the weights *first* and say so, rather
+than optimising the default and describing the result as an improvement.
+
+## Choosing an opponent — this decides what you are measuring
+
+- `--opponent none` — no player at all. What 10 of 11 worlds actually are for most of an
+  Odyssey. Use for development-curve work. Pressure is dropped from the score here.
+- `--opponent passive` (default) — a seated base that never acts. Use to answer "does
+  pressure ever arrive at all".
+- `--opponent turtle` — a real economy behind turrets that never attacks. Use for
+  "can the AI crack a defended base", which is the question that decides whether an
+  Odyssey neighbour is threatening.
+
+A result from one opponent says nothing about the others. State which one you used.
+
+## Search
+
+`node tools/ailab.js search --strategy aggressive --dials 'attackTimeoutMult=0.3:1,garrisonMult=0:1'`
+
+A deterministic coordinate scan — the simplest thing that works. The judgement that matters
+is *which dials to open*, and that is yours: prefer dials whose mechanism you can state in a
+sentence ("commit sooner, with less"), and open at most two or three. Re-run any winner
+through `sweep --seeds 3` on the full roster before believing it — the search optimises a
+noisy mean and will happily overfit three worlds.
+
+## Traps specific to this codebase
+
+- **Layers compose multiplicatively.** Archetype × strategy × difficulty all multiply
+  (`graceMult`, `workerTargetMult`, …). A dial that looks mild in isolation can be a 3×
+  swing on Hard + Aggressive + Rusher. Always sweep across difficulties when touching one.
+- **`neverInitiates` is absolute**, including the skirmish desperation timeout. It was made
+  absolute on purpose (see the comment in `engine/aiStrategy.js`) — a passive player was
+  eating unexplained all-in waves. Do not "fix" the Odyssey side of it by removing the flag;
+  add a separate Odyssey-only provocation path if that's the goal.
+- **Neighbour worlds pick their strategy uniformly at random** (`neighbourAiProfile` in
+  `engine/galaxy.js`), so any change to the STRATEGIES table changes roughly a quarter of the
+  galaxy. Weight the sweep accordingly.
+- **Phase order in `engine/ai.js` `runAI` is load-bearing** — phases share an APM budget and
+  pass ore reserves forward. Production runs before industry, which is why industry starves
+  on a fast-spending archetype. Reordering is a real change; measure it, don't assume it.
+- **The engine must stay pure and deterministic.** No `Math.random`/`Date.now` under
+  `engine/`, ever (`test/engine-purity.test.js`). Sparring bots and metrics belong in
+  `tools/`, never in the engine.

CHANGELOG.md

@@ -6,6 +6,19 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+### Added
+
+- `tools/ailab.js` — a headless bench for the Odyssey AI. Runs the real sim for 30–60 sim-minutes
+  per world (seconds of wall clock), drives the player side with scripted sparring bots, and
+  scores the opponent on development / growth / pressure / thrift / liveness / survival. Candidate
+  AIs are injected as JSON into the archetype, strategy and difficulty tables (`--overrides`), so
+  the whole space can be searched without touching `engine/`. Subcommands: `probe`, `sweep`,
+  `compare`, `search`, `check`. No engine behaviour changed.
+- `docs/odyssey-ai-review.md` — a measured review of how the AI plays in Odyssey, with the
+  findings the bench turned up (a supply deadlock that permanently freezes a developed AI, a
+  terminating build order, a Rusher that never develops, and a non-initiating half of the galaxy),
+  plus the tuning loop to run against them.
+
 ### Changed
 
 - The Refinery, Foundry, and Arsenal no longer double as forward resource drop-offs — they're

README.md

@@ -178,6 +178,9 @@ which is what that "whether it keeps your saves" note above is warning you about
 - `data.js` — pure content (factions, the commodity catalog, production recipes, the charted
   worlds).
 - `tools/serve.js` — the zero-dependency dev server behind `npm start`.
+- `tools/ailab.js` — a headless bench for measuring and tuning the Odyssey AI: it runs the sim
+  without a browser, scores the opponent over a long session, and A/B-tests candidate AIs supplied
+  as JSON. See [docs/odyssey-ai-review.md](docs/odyssey-ai-review.md).
 
 ## Background: why a separate repo
 

docs/odyssey-ai-review.md

@@ -0,0 +1,353 @@
+# The Odyssey AI — review, and a bench for tuning it
+
+Two things live in this document:
+
+1. **A review of the AI as it plays in Odyssey**, backed by measurements rather than by
+   reading the source. Every claim below has a command that reproduces it.
+2. **A proposal for searching and testing better AI strategies** with Claude Code, and the
+   tool that makes it runnable — `tools/ailab.js`.
+
+Nothing under `engine/` changed to produce this. The findings are reported, not fixed;
+fixing them is the first job the bench is for.
+
+---
+
+## 1. How the Odyssey AI is actually built
+
+The opponent is one scripted controller (`engine/ai.js` `runAI`) whose behaviour comes from
+**three plain-data tables composed multiplicatively**, plus a diplomacy ramp that gates
+whether it may attack at all:
+
+| Layer | File | What it sets | Chosen by |
+|---|---|---|---|
+| **Archetype** | `aiArchetypes.js` | temperament: worker target, army size, attack timeout, unit mix, turrets, barracks, expansion, doctrine, faction — plus an `odyssey:` overlay that only applies when `state.diplomacy` exists | the world (`PLANET_ARCHETYPE`) |
+| **Strategy** | `aiStrategy.js` | aggression: whether/when it voluntarily attacks, standing-army cap, war-footing response | the player at setup — or, for neighbour worlds, uniformly at random |
+| **Difficulty** | `aiDifficulty.js` | APM, micro, worker multiplier, grace/grievance, research pace, market access, rusher graduation | the player at setup — or, for neighbour worlds, uniformly at random |
+| **Diplomacy** | `diplomacy.js` | a stance from +1 to −1 driven by scarcity, your kills, the neighbour's own development, late-game creep, tributes, and your Gate. `hostility()` scales muster size, committed fraction and wave cadence | emergent |
+
+`runAI` threads one world snapshot through its decision phases in a load-bearing order
+(scout → workers → found/survive → expand → base/tech → produce/fortify → research → barter →
+industry → military → superweapon), all sharing an APM action budget and forward-passed ore
+reserves. That order matters more than it looks — see §2.4.
+
+**This architecture is genuinely good, and it is what makes the rest of this document
+cheap.** Every dial is read defensively (`|| 1` for multipliers, falsy for flags), so an
+absent layer is a no-op; the tables are plain exported objects; the sim is pure,
+deterministic and headless. Adding a candidate AI is therefore *writing a row into a table*,
+not editing the engine — which is exactly what a search loop needs.
+
+Other things the review found worth stating plainly:
+
+- The AI plays under its own fog (`state.fogAI`) and earns its intel with a scout. Its
+  counter-picking, expansion targets and threat response are all honestly gated on what it
+  has seen.
+- Odyssey offence is a hostility-paced *probe ramp*, not a doomstack: muster, committed
+  fraction and cadence all scale with `hostility()`, and there's a `playerHasPresence` guard
+  so background worlds don't send waves at nobody.
+- The Odyssey-only paths (`state.endless` / `state.diplomacy`) are cleanly separated from the
+  skirmish path, which is why the skirmish stayed byte-identical through all of it.
+
+---
+
+## 2. What the bench measured
+
+Reproduce any row with the command under it. All runs are seeded and deterministic.
+
+The headline: a full-roster soak — **11 worlds × 4 strategies, Medium, 40 sim-minutes each,
+against a player that seats a base and then does nothing** (`node tools/ailab.js check
+--minutes 40`, 44 runs, ~3½ minutes of wall clock) — fires every one of the bench's five
+named defects:
+
+| detector | fires on | what it means |
+|---|---|---|
+| `production-stall` | **43 / 44** | a completed Barracks stood idle while the AI held real money |
+| `hoarding` | **23 / 44** | banked resources peaked above 4,000 with nothing to spend them on |
+| `hostile-but-idle` | **22 / 44** | the HUD reads *Hostile* and no wave ever comes |
+| `dev-flatline` | **19 / 44** | the industry/tech climb stopped and never resumed |
+| `supply-deadlock` | **5 / 44** | production wedged on a unit that can't fit under the supply cap |
+
+Mean quality score across the roster: **0.33 / 1.00**. The sections below take each finding
+apart.
+
+### 2.1 Half the galaxy's neighbours can never attack you
+
+`STRATEGIES` has four rows; two of them (`economic`, `matching`) carry `neverInitiates: true`,
+which blocks **every** voluntary commit. `neighbourAiProfile` (`engine/galaxy.js`) picks a
+neighbour's strategy uniformly from `Object.keys(STRATEGIES)`, so in expectation **half the
+worlds in a galaxy hold a strategy that cannot attack you, ever**, regardless of stance.
+
+Measured across the full roster (11 worlds × 4 strategies, 40 sim-minutes, passive player):
+
+- `economic` and `matching`: **0 waves in all 22 runs**, and the passive player's Command
+  Center still standing in all 22 — with **every** sample where `hostility() >= 0.5` showing
+  zero waves committed. That's the `hostile-but-idle` detector firing 22/44, i.e. on *exactly*
+  the non-initiating half and nothing else.
+- `default` and `aggressive`: 1–3 waves on most worlds (8 on helix), player base razed in the
+  majority.
+
+So the HUD reads *Hostile*, the stance is pinned at −1, and nothing comes. That is the
+single most player-visible AI failure in the mode, and it is a distribution choice
+(`neighbourAiProfile`) meeting an absolute flag (`neverInitiates`), not a bug in either.
+
+The secondary effect is just as costly: a `neverInitiates` neighbour also never *spends*.
+The four highest banked-resource runs in the roster are all `economic`/`matching`
+(helix/matching 36,207 · helix/economic 30,785 · vesper/economic 30,679 · ferros/economic
+28,678), because the strategy caps the standing army at 3–8 units and nothing else in the AI
+can absorb the income.
+
+```
+node tools/ailab.js sweep --strategies economic,matching --minutes 40
+```
+
+`neverInitiates` is absolute *on purpose* — see the comment in `aiStrategy.js`; it was made
+absolute to stop a passive player eating an unexplained all-in wave on the skirmish
+desperation timeout. The fix is therefore not to remove the flag but to give Odyssey its own
+provocation path, or to stop `neighbourAiProfile` sampling the non-initiating strategies
+uniformly.
+
+### 2.2 A hard production deadlock that freezes a developed AI permanently
+
+The unit-mix cycle retries the same entry until it succeeds (`pickNextUnitType` indexes on
+`unitsBuilt`, which only increments on success). The Habitat trigger in `aiBaseAndTech` fires
+at `used >= cap - 2` — a margin sized for a 2-supply unit. The Odyssey roster contains
+4-supply (Dreadnought, Aegis, Colossus) and 8-supply (Leviathan) units.
+
+When the free supply lands in the gap — at least 2 but less than the next mix entry needs —
+neither side moves: production can't queue, and the Habitat that would unblock it is never
+triggered. Measured on kybernet at Medium, 50 sim-minutes, no player:
+
+```
+unitsBuilt 63 -> next mix entry: dreadnought  supplyCost 4
+supply 156 / 158.6   free 2.6
+habitat trigger (used >= cap-2)?  false
+can queue next?                   false
+ore 8031   radioactives 1994
+```
+
+The result is permanent: army frozen at 66 units from minute 40 to minute 60, both Barracks
+queues empty, banked ore climbing 2,797 → 8,031 → 11,476 → 30,000+ with nothing to spend it
+on. The world is finished for the rest of what is an unbounded session.
+
+```
+node tools/ailab.js probe --world kybernet --opponent none --minutes 60 --sample 10
+```
+
+### 2.3 The build order terminates — and this is a play-forever mode
+
+Even without the deadlock, the AI's plan has an end: the factory chain, the tech order, one
+Star Dock, one Plasma Rig, one Helium Bomb. Once it's climbed them, there is nothing left in
+the script to buy. `INDUSTRY_CHAIN` and `RESEARCH_ORDER` are finite lists; `maxBarracks` is 1
+or 2; there is no "spend surplus on more of what works" rule at all.
+
+That shows up as the same signature as the deadlock — banked resources rising, army flat —
+and it is why `thrift` scores 0.00 on every long developed run. A neighbour in a mode with no
+end needs a terminal loop, not a terminal list.
+
+It is also the most widespread finding by far: `production-stall` fires on **43 of 44** runs,
+across every world and every strategy. The single exception (glacius/aggressive) missed the
+detector's 0.25 threshold by scoring 0.11 — it stalled too, just less often.
+
+### 2.4 The Rusher never develops, and its Hard-only rescue lands ~30 minutes late
+
+`rusherGraduates` (Hard) is meant to turn a Rusher into a developer after 20 minutes. On a
+korrath background world it does not visibly land until ~50:
+
+| sim time | dev (medium) | dev (hard) |
+|---|---|---|
+| 10m | 1 | 1 |
+| 20m | 1 | 1 |
+| 30m | 1 | 1 |
+| 40m | 1 | 1 |
+| 50m | 1 | 3 |
+| 60m | 1 | 18 |
+
+At Medium the Rusher is still on 6 workers, dev 1 and four distinct building types at
+**60 minutes**. The mechanism is phase order, not the graduation gate: `aiProduceAndFortify`
+runs *before* `aiIndustry` and holds no reserve, so a cheap-unit archetype spends ore down
+below a Smelter's 160 every think cycle. The Foundry and Refinery already solve exactly this
+with `ctx.foundryReserve` / `ctx.refineryReserve`; the industry chain has no equivalent.
+
+It's all three Rusher worlds, not one: across korrath, nimbus and oort, **9 of 12 runs end at
+dev 1** after 40 minutes. The three exceptions are the `economic` strategy, whose
+`wantsIndustryAlways` flag bypasses the archetype gate entirely and takes them to dev 20 — so
+the capability is there and reachable; it's the archetype path that can't get to it.
+
+```
+node tools/ailab.js probe --world korrath --difficulty hard --opponent none --minutes 60 --sample 10
+```
+
+### 2.5 A wiped neighbour is gone forever
+
+`aiFoundOrSurvive` can re-seat a razed base — but only from a colony ship in hand, and
+`aiExpand`'s Odyssey branch only *produces* one when a standing Command Center exists
+(`!colonyShip && cc && workers.length > 0`). Lose the CC without a ship in flight and the AI
+is permanently dead: no workers, no production, no recovery.
+
+Against the `turtle` sparring bot (a plain economy behind four turrets that never attacks),
+an Aggressive Rusher on korrath threw itself away: base gone by minute 10, last worker gone by
+minute 20, and for the remaining five minutes of the run — and every minute after it — no
+Command Center, no production, and 1,143 ore banked forever.
+
+For the *player's* conquest that's correct and intended (`galaxy.pacified` treats it as a
+milestone). For a world the player has never visited, it means a background world can quietly
+die and stay dead.
+
+```
+node tools/ailab.js probe --world korrath --strategy aggressive --opponent turtle --minutes 25
+```
+
+### 2.6 The multiplicative layers have no clamp
+
+`graceMult` and `grievanceMult` multiply across all three layers with no bound:
+
+```
+grace = 420s × archetype × strategy × difficulty
+      = 420 × 0.5 (Rusher) × 0.2 (Aggressive) × 0.9 (Hard) = 37.8s
+```
+
+The 7-minute opening grace — documented as the window that lets a player establish before a
+world can turn — collapses to under 40 seconds on a reachable setup-screen combination
+(Aggressive + Hard on a Rusher world). Grievance goes the other way: 0.04 × 2 × 1.6 × 1.15 =
+0.147 per kill, so about ten kills drag a neighbour from its opening stance (+0.35) to fully
+hostile. Neither is necessarily wrong, but both are *unintended* consequences of composition,
+and nothing in the tests notices.
+
+### 2.7 The AI does not play the Odyssey
+
+The neighbour plays a skirmish with extra buildings. It never builds a Spaceport, never
+jumps, never settles another world, never trades for credits, never charges a Gate, never
+offers or demands tribute. `checkExpansion` gives the *appearance* of faction spread, but it
+is a starmap bookkeeping pass — it sets `galaxy.claims` and relabels the target world's AI
+faction; no AI actually goes anywhere.
+
+This is a design gap rather than a defect, and it's the largest single lever on how alive the
+galaxy feels.
+
+### 2.8 There is no AI-vs-AI, but there nearly is
+
+`state.ai` is a single controller slot bound to owner `"ai"`. Across the AI modules
+there are only ~21 owner-literal references, and `engine/state.js` already keeps the
+owner-generic scaffold (`state.owners`, per-owner fog, owner-keyed bases). Making the
+controller owner-parametric — `state.ais[owner]` — is a contained refactor, and it would
+unlock true self-play: the strongest possible evaluation signal, replacing the scripted
+sparring bots below.
+
+---
+
+## 3. The proposal — searching for better AI with Claude Code
+
+### 3.1 Why the usual approach doesn't work here
+
+The existing suite is excellent at invariants (determinism, purity, "a skirmish resolves to a
+winner on all nine worlds") and useless for quality. AI quality in Odyssey is a *curve over
+40+ minutes* — does it keep developing, does it spend what it earns, does pressure arrive in
+proportion to hostility — and no assertion expresses that. Every finding in section 2 sat in
+a suite of ~90 green test files.
+
+So the missing piece is not more tests. It's a **measurement loop**.
+
+### 3.2 The bench: `tools/ailab.js`
+
+Zero dependencies, Node stdlib only, in `tools/` (never `engine/`, which stays pure). It runs
+the real sim headlessly — a 40-sim-minute world costs ~7 seconds — samples a metric set on a
+fixed cadence, and prints a scoreboard.
+
+```
+node tools/ailab.js probe    # one configuration, full time series
+node tools/ailab.js sweep    # a matrix of worlds × strategies × difficulties → scoreboard + JSON
+node tools/ailab.js compare  # A/B two saved sweeps, per-configuration deltas
+node tools/ailab.js search   # deterministic coordinate scan over a strategy's dials
+node tools/ailab.js check    # the named-defect list from section 2, across the roster
+```
+
+**A candidate AI is JSON, not a patch.** Because the three tables are plain objects read
+through defensive accessors, `--overrides` writes rows into them before a run:
+
+```json
+{
+  "strategies":   { "swarm":  { "armyAttackSizeMult": 0.5, "garrisonMult": 0.2 } },
+  "archetypes":   { "rusher": { "odyssey": { "workerTarget": 9 } } },
+  "difficulties": { "hard":   { "workerTargetMult": 1.4 } }
+}
+```
+
+That is the whole reason this is a day of work and not a project: **the search space is
+already a JSON document.**
+
+**Sparring opponents.** An AI with nobody to react to is playing solitaire, so the bench
+drives the player side with scripted bots through the engine's public command API:
+
+| bot | what it is | the question it answers |
+|---|---|---|
+| `none` | no player at all | how does the development curve look on a background world? |
+| `passive` | seats a base, never acts | does pressure ever arrive at all? |
+| `turtle` | economy behind turrets, never attacks | can the AI crack a defended base? |
+
+**Metrics and score.** Six components, weighted in `WEIGHTS` and printed individually:
+`develop` (climbs the chain), `keepGrowing` (still growing in the last third — the
+play-forever requirement), `pressure` (commits waves once actually hostile), `thrift`
+(spends what it earns), `liveness` (production never wedges), `survive`. The weights are
+the definition of "better AI" and are meant to be argued with and edited; the components are
+printed because a total nobody can decompose is a number nobody should trust.
+
+**Health checks.** Each finding in section 2 is encoded as a named detector
+(`supply-deadlock`, `hoarding`, `dev-flatline`, `hostile-but-idle`, `production-stall`) so it
+is a reproducible list that shrinks as the AI improves, rather than a paragraph that rots.
+
+`test/ailab.test.js` guards the bench itself: that runs are deterministic (or a "+0.04
+improvement" is indistinguishable from noise) and that the override seam actually reaches the
+sim (or every search measures the baseline against itself).
+
+### 3.3 The loop to run with Claude Code
+
+Packaged as a skill at `.claude/skills/ai-lab/SKILL.md`, so Claude picks it up whenever the
+work is about tuning the opponent. The loop it encodes:
+
+1. **Baseline** a sweep to JSON. Never compare against remembered numbers.
+2. **Name the component you intend to move** before changing anything.
+3. **One hypothesis**, expressed as an overrides file.
+4. **Sweep the candidate, then `compare`** — read the per-configuration deltas, not the mean.
+   A mean that improved because one world improved a lot is a regression in disguise.
+5. **Guardrails, every time:** `npm test` (determinism, purity, the resolve guarantee),
+   `ailab check` (the defect list must not grow), and a check that the skirmish path is
+   untouched if only Odyssey was meant to change.
+6. **Record it in the ledger below — including the failures**, so the next session doesn't
+   re-run a dead end.
+
+The division of labour that makes this worth doing: the bench supplies reproducibility and
+measurement; Claude supplies the part that's expensive for a human — reading a 40-row
+scoreboard against the code that produced it, forming a mechanism-level hypothesis, and
+turning it into the next overrides file. The judgement about *what the AI should feel like*
+stays with you, encoded in `WEIGHTS`.
+
+### 3.4 Suggested order of work
+
+Sequenced so each step makes the next one measurable:
+
+1. **Fix the supply deadlock** (§2.2) — a one-line-shaped fix (size the Habitat trigger to
+   the largest supply cost in the effective mix, or skip a mix entry that can't fit rather
+   than retrying it). It's the cheapest, and it currently corrupts every long-run
+   measurement.
+2. **Give the industry chain an ore reserve** like the Foundry's (§2.4), so development isn't
+   starved by unit production. Then re-measure whether `rusherGraduates` needs to exist.
+3. **Add a surplus sink** (§2.3): more Barracks / more expansions / a repeatable late-game
+   purchase, so a developed economy has somewhere to put its income. This is the change that
+   makes "play forever" true for the AI as well as the player.
+4. **Decide what a non-initiating neighbour means in Odyssey** (§2.1) — either weight
+   `neighbourAiProfile` away from them, or give Odyssey a provocation path that a
+   `neverInitiates` strategy still answers.
+5. **Then** search the dials (§3.3). Tuning multipliers on top of a deadlocked, starving,
+   hoarding AI is fitting noise.
+6. **Optional, high leverage:** make the controller owner-parametric (§2.8) and replace the
+   sparring bots with self-play.
+
+---
+
+## 4. Search ledger
+
+One row per experiment, including the ones that didn't work. Unrecorded negative results get
+re-run.
+
+| date | hypothesis | overrides | result | kept? |
+|---|---|---|---|---|
+| 2026-07-30 | — (baseline) | — | `check --minutes 40`, 44 runs: mean score **0.328**. production-stall 43/44 · hoarding 23/44 · hostile-but-idle 22/44 · dev-flatline 19/44 · supply-deadlock 5/44 | n/a |

test/ailab.test.js

@@ -0,0 +1,104 @@
+/* ============================================================
+   Guards for tools/ailab.js — the headless AI bench (see docs/odyssey-ai-review.md).
+
+   The bench exists to answer "did this AI change help?", so the bench itself has to be
+   trustworthy in exactly two ways, and these tests pin both:
+
+     1. DETERMINISM. Two runs of the same configuration must produce identical numbers,
+        or a "+0.04 improvement" is indistinguishable from noise and the whole loop is
+        theatre. The engine is already deterministic; what this guards is that the lab
+        (its sparring bots, its sampling cadence, its seed derivation) doesn't smuggle in
+        a wall-clock or an unseeded pick.
+     2. THE OVERRIDE SEAM. A candidate AI is injected as data into the ARCHETYPES /
+        STRATEGIES / DIFFICULTY_OPTIONS tables. If that injection silently no-ops, every
+        search result is a measurement of the baseline against itself.
+
+   Runs are short (a few sim-minutes) — this suite guards the harness, not the AI. The
+   long soak lives behind `node tools/ailab.js check`, which is a tool you run, not a test
+   that runs you: several of its findings fire today on purpose.
+   ============================================================ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { run, summarise, score, applyOverrides, CHECKS, OPPONENTS, WORLDS, WEIGHTS } from "../tools/ailab.js";
+import { STRATEGIES } from "../engine/aiStrategy.js";
+
+const short = extra => ({ world: "ferros", strategy: "default", difficulty: "medium",
+                          opponent: "passive", minutes: 4, sample: 2, seed: 7, ...extra });
+
+// Compare only the summary fields — the curve is a superset of them, so a divergence
+// anywhere in the run shows up here too, without a 40-field diff to read.
+const fingerprint = r => JSON.stringify(summarise(r.curve));
+
+test("a lab run is deterministic — same configuration, byte-identical metrics", () => {
+  assert.equal(fingerprint(run(short())), fingerprint(run(short())),
+    "two identical lab runs diverged: something in the harness reads a clock or an unseeded pick");
+});
+
+test("the seed genuinely varies the run (the lab isn't pinned to one world roll)", () => {
+  const a = run(short({ seed: 7 })), b = run(short({ seed: 99 }));
+  assert.notEqual(fingerprint(a), fingerprint(b), "two different seeds produced identical metrics");
+});
+
+test("each sparring opponent sets up the player side it advertises", () => {
+  const presence = opponent => {
+    const r = run(short({ opponent, minutes: 2 }));
+    return r.curve[r.curve.length - 1].playerBuildings;
+  };
+  assert.equal(presence("none"), 0, "the background-world opponent leaves no player presence at all");
+  assert.ok(presence("passive") >= 1, "the passive opponent seats a Command Center");
+  assert.ok(presence("turtle") >= 1, "the turtle opponent seats a Command Center");
+  for (const [id, bot] of Object.entries(OPPONENTS))
+    assert.equal(typeof bot.desc, "string", `opponent ${id} needs a one-line description for the scoreboard`);
+});
+
+test("the turtle bot actually builds an economy — it's a yardstick, not a statue", () => {
+  const r = run(short({ opponent: "turtle", minutes: 8, world: "ferros" }));
+  const last = r.curve[r.curve.length - 1];
+  assert.ok(last.playerBuildings > 1, `the turtle should raise more than its Command Center (got ${last.playerBuildings})`);
+});
+
+test("an overrides row reaches the sim — a strategy that never initiates commits no waves", () => {
+  // The seam the whole search loop rests on: STRATEGIES is a plain object read through
+  // strategyFor(), so writing a row into it before a run IS the experiment.
+  applyOverrides({ strategies: { labPacifist: { neverInitiates: true } } });
+  assert.ok(STRATEGIES.labPacifist, "applyOverrides must add the row to the live table");
+  const pacifist = run(short({ strategy: "labPacifist", world: "korrath", minutes: 12 }));
+  const baseline = run(short({ strategy: "default", world: "korrath", minutes: 12 }));
+  assert.equal(pacifist.waves, 0, "a neverInitiates strategy must commit zero waves");
+  assert.ok(baseline.waves > 0, "the korrath baseline should commit at least one wave in 12 minutes");
+});
+
+test("applyOverrides merges into an existing row rather than replacing it", () => {
+  applyOverrides({ strategies: { aggressive: { garrisonMult: 0.9 } } });
+  assert.equal(STRATEGIES.aggressive.garrisonMult, 0.9, "the overridden field is applied");
+  assert.equal(STRATEGIES.aggressive.attackTimeoutMult, 0.55, "…and the untouched fields survive");
+});
+
+test("score components stay in 0..1 and the total is their weighted mean", () => {
+  const r = run(short({ minutes: 3 }));
+  const s = score(r);
+  for (const [k, v] of Object.entries(s.parts))
+    assert.ok(v >= 0 && v <= 1, `component ${k} out of range: ${v}`);
+  const wsum = Object.keys(s.parts).reduce((a, k) => a + WEIGHTS[k], 0);
+  const expected = Object.entries(s.parts).reduce((a, [k, v]) => a + (WEIGHTS[k] / wsum) * v, 0);
+  assert.ok(Math.abs(s.total - expected) < 1e-3, `total ${s.total} isn't the weighted mean ${expected}`);
+});
+
+test("scoring an opponent-less run drops the pressure component instead of scoring zero for it", () => {
+  // Nobody to attack means "did it apply pressure?" is unanswerable, not answered badly —
+  // scoring it 0 would make the right setting for development work look like a bad AI.
+  const s = score(run(short({ opponent: "none", minutes: 3 })));
+  assert.ok(!("pressure" in s.parts), "pressure must be dropped when there is no player at all");
+  assert.ok(s.total > 0, "the remaining components still produce a usable score");
+});
+
+test("every health check is well-formed and covers the whole Odyssey roster", () => {
+  const ids = CHECKS.map(c => c.id);
+  assert.equal(new Set(ids).size, ids.length, "check ids must be unique — they name findings in reports");
+  for (const c of CHECKS) {
+    assert.equal(typeof c.hit, "function");
+    assert.ok(c.why && c.why.length > 20, `check ${c.id} needs a why: line explaining the mechanism`);
+  }
+  assert.equal(WORLDS.length, 11, "the lab sweeps the full Odyssey roster (nine skirmish worlds + two extras)");
+});

tools/ailab.js

@@ -0,0 +1,619 @@
+/* ============================================================
+   AI LAB — a headless bench for the Odyssey opponent, so "is this AI any good?"
+   becomes a measurement instead of an opinion.
+
+   The engine test suite already guards INVARIANTS (determinism, purity, "a skirmish
+   resolves to a winner"). Nothing measures QUALITY: whether the neighbour on an
+   Odyssey world develops, spends what it earns, and applies pressure in proportion to
+   how hostile it has become. Those are curves over 30–60 minutes of sim, not
+   assertions, and they're exactly what breaks silently when an archetype number moves.
+
+   This tool runs the sim headlessly (it's already pure and deterministic — that's the
+   whole reason this is cheap), samples an AI-quality metric set on a fixed cadence, and
+   prints a scoreboard. Because the AI's whole behaviour space is three plain-data
+   tables — ARCHETYPES × STRATEGIES × DIFFICULTY_OPTIONS, all read through defensive
+   `|| 1` accessors — a candidate strategy is a JSON object, not a code change: pass
+   --overrides and the lab writes new rows into those tables before it runs. So
+   searching for a better AI needs no engine edit at all.
+
+   Usage
+     node tools/ailab.js probe   [--world ferros] [--strategy default] [--difficulty medium]
+                                 [--opponent passive] [--minutes 40] [--sample 5]
+     node tools/ailab.js sweep   [--worlds a,b] [--strategies a,b] [--difficulties a,b]
+                                 [--seeds 3] [--minutes 40] [--json out.json] [--csv out.csv]
+     node tools/ailab.js compare --baseline base.json --candidate cand.json
+     node tools/ailab.js search  --strategy aggressive --dials 'attackTimeoutMult=0.3:1,garrisonMult=0:1'
+                                 [--trials 24] [--worlds a,b]
+     node tools/ailab.js check   [--worlds a,b] [--minutes 60]      # health checks (stall/hoard/flatline)
+
+   Common flags
+     --overrides f.json   inject rows into the AI tables before running, e.g.
+                          { "strategies": { "swarm": { "armyAttackSizeMult": 0.5 } },
+                            "archetypes": { "rusher": { "odyssey": { "workerTarget": 9 } } },
+                            "difficulties": { "hard": { "workerTargetMult": 1.4 } } }
+     --seed N             base seed (default 1) — every run is reproducible from it
+
+   Deterministic by construction: every world seeds from mulberry32, every sparring
+   opponent is scripted off the sim clock, and no wall-clock or Math.random is read. Two
+   runs of the same command produce byte-identical numbers.
+
+   Lives in tools/ (a dev bench, like tools/serve.js) — NOT in engine/, which stays the
+   pure shipped simulation. It only ever READS the engine's public API.
+   ============================================================ */
+
+"use strict";
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { createGameState } from "../engine/state.js";
+import { tick } from "../engine/sim.js";
+import { createDiplomacy, hostility, aiDevelopment } from "../engine/diplomacy.js";
+import { createMarket } from "../engine/market.js";
+import { deployColonyShip } from "../engine/colony.js";
+import { findPlacement } from "../engine/colliders.js";
+import { issueBuild } from "../engine/commands.js";
+import { queueProduction } from "../engine/production.js";
+import { supplyUsed, supplyCap } from "../engine/supply.js";
+import { BUILDINGS, UNITS, canAfford } from "../engine/entities.js";
+import { pickNextUnitType } from "../engine/aiMilitary.js";
+import { ARCHETYPES, archetypeFor, PLANET_ARCHETYPE, ODYSSEY_EXTRA_ARCHETYPE } from "../engine/aiArchetypes.js";
+import { STRATEGIES } from "../engine/aiStrategy.js";
+import { DIFFICULTY_OPTIONS } from "../engine/aiDifficulty.js";
+import { mulberry32, hashStr } from "../engine/rng.js";
+
+const WORLDS = [...Object.keys(PLANET_ARCHETYPE), ...Object.keys(ODYSSEY_EXTRA_ARCHETYPE)];
+const DT = 0.1;                  // the sim's fixed step, same as the game loop
+const THINK = 1.5;               // sparring-bot decision cadence, matching the AI's own think interval
+
+/* ============================================================
+   THE LAB WORLD
+   ============================================================ */
+
+// One Odyssey world, built exactly the way engine/galaxy.js addPlanet builds a neighbour:
+// endless, with its own market and diplomacy, the archetype's faction, and the AI dials under
+// test. The `opponent` decides what the player side is, which is what the AI is actually being
+// measured against — see the sparring bots below.
+function labWorld({ world, strategy, difficulty, opponent, seed }) {
+  const s = createGameState({
+    planetId: world, seed, rng: mulberry32(seed), endless: true,
+    aiStrategy: strategy, difficulty,
+    aiApm: null, aiMicro: !!DIFFICULTY_OPTIONS.find(o => o.mult === difficulty)?.aiMicro,
+    aiFaction: archetypeFor(world).faction,
+  });
+  s.diplomacy = createDiplomacy();
+  s.market = createMarket(s);
+  s.inGalaxy = true;             // galaxy states never resolve per-world (engine/victory.js)
+  const bot = OPPONENTS[opponent];
+  if (!bot) throw new Error(`unknown opponent "${opponent}" — one of: ${Object.keys(OPPONENTS).join(", ")}`);
+  bot.setup(s);
+  return { state: s, bot };
+}
+
+/* ============================================================
+   SPARRING OPPONENTS — what the AI is measured against
+
+   An Odyssey neighbour with nobody to react to is playing solitaire, so a metric taken
+   with no opponent only measures its build order. Each bot below drives the "player"
+   side through the engine's PUBLIC command API (the same calls input.js makes), off the
+   sim clock, with no randomness — so a measurement is repeatable and the difference
+   between two AI configs is the only thing that moves.
+
+   These are deliberately dumb and legible. A sparring partner you can't describe in a
+   sentence makes a scoreboard you can't interpret.
+   ============================================================ */
+
+const playerUnitsOf = (s, type) => [...s.units.values()].filter(u => u.owner === "player" && u.type === type);
+const playerBuildingsOf = (s, type) =>
+  [...s.buildings.values()].filter(b => b.owner === "player" && (!type || b.type === type));
+
+// Deploy the opening colony ship into a real Command Center — every bot but `none` starts here,
+// because an undeployed ship is a foothold the AI's wave logic reads but can't meaningfully fight.
+function seatBase(s) {
+  const ship = playerUnitsOf(s, "colonyship")[0];
+  if (ship) deployColonyShip(s, ship.id);
+}
+
+// Keep idle player workers mining, using the PLAYER's own fog for discovery (the AI's
+// assignIdleWorkers reads state.fogAI, so it can't be reused here without handing the bot
+// the AI's intel). Nearest live discovered node, ore first — deliberately simpler than the
+// AI's saturation-aware steering, since the bot is a yardstick, not a contender.
+function botGather(s) {
+  const live = s.map.nodes.filter(n => n.amount > 0 && !n.hidden);
+  if (!live.length) return;
+  const ore = live.filter(n => n.com === "ore");
+  for (const w of playerUnitsOf(s, "worker")) {
+    if (w.order) continue;
+    const pool = ore.length ? ore : live;
+    let best = null, bestD = Infinity;
+    for (const n of pool) {
+      const d = Math.hypot(n.x - w.x, n.y - w.y);
+      if (d < bestD) { bestD = d; best = n; }
+    }
+    if (best) w.order = { type: "gather", nodeId: best.id };
+  }
+}
+
+// Put `type` down near the player's CC, sliding off collisions the same way the AI does.
+function botBuild(s, type, dx, dy) {
+  const cc = playerBuildingsOf(s, "command").find(b => !b.constructing);
+  const worker = playerUnitsOf(s, "worker").find(w => !w.order || w.order.type === "gather");
+  if (!cc || !worker || !canAfford(s.players.player.resources, BUILDINGS[type].cost)) return false;
+  const spot = findPlacement(s, type, cc.x + dx, cc.y + dy);
+  return !!spot && issueBuild(s, worker.id, type, spot.x, spot.y);
+}
+
+const OPPONENTS = {
+  // A living-galaxy BACKGROUND world: no player at all. This is what 10 of the 11 worlds
+  // actually are for most of an Odyssey, so it's the honest setting for measuring the
+  // development curve — and the one where a frozen build order shows up bare.
+  none: {
+    desc: "no player at all (a living-galaxy background world)",
+    setup(s) {
+      for (const [id, u] of [...s.units]) if (u.owner === "player") s.units.delete(id);
+      for (const [id, b] of [...s.buildings]) if (b.owner === "player") s.buildings.delete(id);
+      s.background = true;
+    },
+    think() {},
+  },
+
+  // Seats a base and then does NOTHING — the "player who wandered off". Measures whether
+  // pressure ever actually arrives: an AI that can't beat this one will never threaten anyone.
+  passive: {
+    desc: "seats a Command Center, then never acts again",
+    setup: seatBase,
+    think() {},
+  },
+
+  // A real economy that never attacks: workers to target, Habitats ahead of the cap, a
+  // Barracks, defenders, and turrets. The yardstick for "can the AI crack a defended base",
+  // which is the question that actually matters for an Odyssey neighbour.
+  turtle: {
+    desc: "economy + static defence, never attacks (the base-cracking yardstick)",
+    setup: seatBase,
+    think(s) {
+      botGather(s);
+      const cc = playerBuildingsOf(s, "command").find(b => !b.constructing);
+      if (!cc) return;
+      const res = s.players.player.resources;
+      const workers = playerUnitsOf(s, "worker").length;
+      if (workers < 12 && cc.queue.length === 0) { queueProduction(s, cc.id, "worker"); return; }
+      if (supplyUsed(s, "player") >= supplyCap(s, "player") - 4
+          && !playerBuildingsOf(s, "habitat").some(b => b.constructing)) { botBuild(s, "habitat", 0, 90); return; }
+      const rax = playerBuildingsOf(s, "barracks").filter(b => !b.constructing);
+      if (!playerBuildingsOf(s, "barracks").length) { botBuild(s, "barracks", 90, -90); return; }
+      if (playerBuildingsOf(s, "turret").length < 4 && canAfford(res, BUILDINGS.turret.cost)) {
+        const i = playerBuildingsOf(s, "turret").length;
+        if (botBuild(s, "turret", 120 - 60 * (i % 2), 120 * (i < 2 ? 1 : -1))) return;
+      }
+      // A standing guard, cheapest-first so the bot's composition never depends on tech it
+      // hasn't built. Units hold at the rally point; the bot never issues an attack order.
+      const idle = rax.find(b => b.queue.length === 0);
+      if (idle && canAfford(res, UNITS.skiff.cost)) queueProduction(s, idle.id, "skiff");
+    },
+  },
+};
+
+/* ============================================================
+   METRICS
+
+   Everything here is read off sim state, never off the AI's own bookkeeping where a
+   cheaper read exists — the point is to measure what the AI DID, not what it intended.
+   ============================================================ */
+
+const oreValue = cost => (cost.ore || 0) + 2 * (cost.crystals || 0) + 2 * (cost.radioactives || 0);
+
+function sample(s) {
+  const ai = [...s.units.values()].filter(u => u.owner === "ai");
+  const army = ai.filter(u => UNITS[u.type].role === "combat");
+  const done = [...s.buildings.values()].filter(b => b.owner === "ai" && !b.constructing);
+  const rax = done.filter(b => b.type === "barracks");
+  const res = s.players.ai.resources;
+  const banked = oreValue(res);
+  const next = rax.length ? pickNextUnitType(s, s.ai.archetype) : null;
+  return {
+    t: Math.round(s.time),
+    workers: ai.filter(u => u.type === "worker").length,
+    army: army.length,
+    armyValue: army.reduce((v, u) => v + oreValue(UNITS[u.type].cost), 0),
+    dev: aiDevelopment(s),
+    buildings: done.length,
+    banked: Math.round(banked),
+    stance: +s.diplomacy.stance.toFixed(3),
+    hostility: +hostility(s).toFixed(3),
+    waves: s.ai.waveCount || 0,
+    // IDLE PRODUCTION: a completed Barracks with an empty queue while the AI is sitting on
+    // real money. Not "it's between jobs" — it's the signature of an AI that has run out of
+    // things it knows how to buy, which in a play-forever mode is the failure that matters.
+    idleRax: rax.filter(b => b.queue.length === 0).length,
+    rax: rax.length,
+    // Is the next mix entry unaffordable in SUPPLY specifically? The mix cycle retries the same
+    // entry until it succeeds, so a unit that doesn't fit under the cap wedges production —
+    // and the Habitat trigger only fires within 2 supply of the cap, which doesn't cover the
+    // 4- and 8-supply Odyssey units. That combination is a hard deadlock, so it's measured.
+    supplyBlocked: !!next && supplyUsed(s, "ai") + (UNITS[next].supplyCost || 0) > supplyCap(s, "ai"),
+    supplyFree: +(supplyCap(s, "ai") - supplyUsed(s, "ai")).toFixed(1),
+    playerBuildings: playerBuildingsOf(s).length,
+    aiAlive: done.some(b => b.type === "command"),
+  };
+}
+
+// Run one configuration and fold its samples into a result row. `minutes` is SIM time; a
+// 40-minute world costs a few seconds of wall clock, which is what makes a sweep practical.
+function run(cfg) {
+  const { state, bot } = labWorld(cfg);
+  const stepsPerSample = Math.round(cfg.sample * 60 / DT);
+  const total = Math.round(cfg.minutes * 60 / DT);
+  const curve = [];
+  let sinceThink = 0;
+  for (let i = 0; i < total; i++) {
+    tick(state, DT);
+    sinceThink += DT;
+    if (sinceThink >= THINK) { sinceThink = 0; bot.think(state); }
+    if (i % stepsPerSample === 0) curve.push(sample(state));
+  }
+  curve.push(sample(state));
+  return { ...cfg, curve, ...summarise(curve) };
+}
+
+// Collapse a curve into the handful of numbers a scoreboard can rank. Deliberately few: a
+// metric nobody can act on is noise.
+function summarise(curve) {
+  const last = curve[curve.length - 1];
+  const peak = key => curve.reduce((m, c) => Math.max(m, c[key]), 0);
+  // The tail is the last third of the run — the play-forever regime, where an AI whose plan
+  // has run out looks identical to one that's still going unless you look at the derivative.
+  const tail = curve.slice(Math.floor(curve.length * 2 / 3));
+  const devGrowthTail = tail.length > 1 ? tail[tail.length - 1].dev - tail[0].dev : 0;
+  const armyGrowthTail = tail.length > 1 ? tail[tail.length - 1].army - tail[0].army : 0;
+  const firstWave = curve.find(c => c.waves > 0);
+  const hostileSamples = curve.filter(c => c.hostility >= 0.5 && c.playerBuildings > 0);
+  return {
+    devFinal: last.dev,
+    devGrowthTail,
+    armyFinal: last.army,
+    armyValueFinal: last.armyValue,
+    armyGrowthTail,
+    workersFinal: last.workers,
+    buildingsFinal: last.buildings,
+    bankedFinal: last.banked,
+    bankedPeak: peak("banked"),
+    waves: last.waves,
+    firstWaveAt: firstWave ? firstWave.t : null,
+    // Fraction of the run spent hostile-but-idle: the neighbour reads "Hostile" in the HUD
+    // while never committing a wave. The single most player-visible AI failure in Odyssey.
+    hostileIdleFrac: hostileSamples.length
+      ? +(hostileSamples.filter(c => c.waves === 0).length / hostileSamples.length).toFixed(2) : 0,
+    // Fraction of samples where a Barracks stood idle on 400+ banked value.
+    idleRichFrac: +(curve.filter(c => c.rax > 0 && c.idleRax > 0 && c.banked > 400).length / curve.length).toFixed(2),
+    supplyDeadlockFrac: +(curve.filter(c => c.supplyBlocked && c.banked > 400).length / curve.length).toFixed(2),
+    stanceFinal: last.stance,
+    playerBuildingsFinal: last.playerBuildings,
+    aiAlive: last.aiAlive,
+  };
+}
+
+/* ============================================================
+   SCORING — one number to rank candidates, and the components that explain it
+
+   A scalar is what a search loop needs; the components are what a HUMAN needs to accept
+   or reject the result. Both are printed, always. Weights are here in the open so an
+   argument about what "better AI" means is an argument about these six lines, not about
+   the harness.
+   ============================================================ */
+
+const clamp01 = v => v < 0 ? 0 : v > 1 ? 1 : v;
+
+export const WEIGHTS = {
+  develop: 0.25,     // climbs the industry/tech chain rather than flatlining on a 2-building base
+  keepGrowing: 0.2,  // and is STILL growing in the last third — the play-forever requirement
+  pressure: 0.25,    // commits waves when it has actually turned hostile
+  thrift: 0.15,      // spends what it earns instead of banking an unusable pile
+  liveness: 0.1,     // production never wedges (idle Barracks on real money)
+  survive: 0.05,     // still holds a Command Center at the end
+};
+
+export function score(r) {
+  const parts = {
+    develop: clamp01(r.devFinal / 20),                      // ~20 = the full chain + most of the tree
+    keepGrowing: clamp01((r.devGrowthTail + Math.max(0, r.armyGrowthTail) / 5) / 4),
+    pressure: r.hostileIdleFrac > 0 ? clamp01(1 - r.hostileIdleFrac) : clamp01(r.waves / 6),
+    thrift: clamp01(1 - r.bankedPeak / 4000),
+    liveness: clamp01(1 - Math.max(r.idleRichFrac, r.supplyDeadlockFrac)),
+    survive: r.aiAlive ? 1 : 0,
+  };
+  // Against the `none` opponent there is nobody to attack, so scoring pressure would just
+  // punish the setting that's RIGHT for measuring development. Drop that component and
+  // renormalise the remaining weights, rather than quietly scoring an unanswerable question.
+  const applicable = Object.keys(WEIGHTS).filter(k => !(k === "pressure" && r.opponent === "none"));
+  const wsum = applicable.reduce((a, k) => a + WEIGHTS[k], 0);
+  const total = applicable.reduce((sum, k) => sum + (WEIGHTS[k] / wsum) * parts[k], 0);
+  if (r.opponent === "none") delete parts.pressure;
+  return { total: +total.toFixed(3), parts };
+}
+
+/* ============================================================
+   OVERRIDES — a candidate AI is DATA, not a patch
+
+   ARCHETYPES / STRATEGIES / DIFFICULTY_OPTIONS are plain exported objects read through
+   `|| 1`-style accessors, so writing a row into them before a run is the whole mechanism
+   for trying a new AI. That's why searching this space needs no engine change: the search
+   space is already a JSON document.
+   ============================================================ */
+
+export function applyOverrides(ov = {}) {
+  for (const [name, row] of Object.entries(ov.strategies || {}))
+    STRATEGIES[name] = { name, desc: "(lab candidate)", ...(STRATEGIES[name] || {}), ...row };
+  for (const [name, row] of Object.entries(ov.archetypes || {})) {
+    const base = ARCHETYPES[name] || ARCHETYPES.balanced;
+    ARCHETYPES[name] = { ...base, ...row, odyssey: { ...(base.odyssey || {}), ...(row.odyssey || {}) } };
+  }
+  for (const [key, row] of Object.entries(ov.difficulties || {})) {
+    const i = DIFFICULTY_OPTIONS.findIndex(o => o.mult === key);
+    if (i >= 0) DIFFICULTY_OPTIONS[i] = { ...DIFFICULTY_OPTIONS[i], ...row };
+  }
+}
+
+/* ============================================================
+   HEALTH CHECKS — the findings this bench already turned up, encoded
+
+   Each is a named, reproducible defect rather than a paragraph in a review doc: run the
+   check, get the list of worlds it fires on. Fix the AI and the list shrinks. These are
+   REPORTED, not asserted — the tool's job is to measure, and today several of them fire.
+   ============================================================ */
+
+export const CHECKS = [
+  { id: "supply-deadlock",
+    why: "the mix cycle retries one unit forever because it doesn't fit under the supply cap, "
+       + "while the Habitat trigger (used >= cap - 2) never fires for a 4- or 8-supply unit",
+    hit: r => r.supplyDeadlockFrac > 0.1 },
+  { id: "hoarding",
+    why: "banked resources the AI has no way to spend — income outruns its build order",
+    hit: r => r.bankedPeak > 4000 },
+  { id: "dev-flatline",
+    why: "the industry/tech climb stopped: no development gained in the last third of the run",
+    hit: r => r.devGrowthTail === 0 && r.devFinal < 12 },
+  { id: "hostile-but-idle",
+    why: "the HUD reads Hostile and the neighbour never commits a wave",
+    hit: r => r.hostileIdleFrac > 0.5 },
+  { id: "production-stall",
+    why: "a completed Barracks stood idle while the AI held real money",
+    hit: r => r.idleRichFrac > 0.25 },
+];
+
+/* ============================================================
+   CLI
+   ============================================================ */
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) out[a.slice(2)] = (argv[i + 1] && !argv[i + 1].startsWith("--")) ? argv[++i] : "true";
+    else out._.push(a);
+  }
+  return out;
+}
+
+const list = (v, fallback) => (v ? String(v).split(",").map(x => x.trim()).filter(Boolean) : fallback);
+const num = (v, d) => (v === undefined ? d : Number(v));
+
+// Just the dials under search, so a search log shows what moved rather than the whole row.
+const pickDials = (row, dials) => Object.fromEntries(dials.map(d => [d.k, row[d.k]]));
+
+// Every run's seed is derived from (base seed, world, strategy, difficulty, replicate) so a
+// row reproduces on its own — you can re-probe exactly one line of a sweep.
+const runSeed = (base, world, strategy, difficulty, rep) =>
+  hashStr(`${base}:${world}:${strategy}:${difficulty}:${rep}`);
+
+function baseConfig(args) {
+  return {
+    minutes: num(args.minutes, 40),
+    sample: num(args.sample, 5),
+    opponent: args.opponent || "passive",
+    seedBase: num(args.seed, 1),
+  };
+}
+
+function runMatrix(args, { worlds, strategies, difficulties, seeds }) {
+  const base = baseConfig(args);
+  const rows = [];
+  for (const world of worlds)
+    for (const strategy of strategies)
+      for (const difficulty of difficulties)
+        for (let rep = 0; rep < seeds; rep++)
+          rows.push(run({ ...base, world, strategy, difficulty,
+                          seed: runSeed(base.seedBase, world, strategy, difficulty, rep) }));
+  return rows;
+}
+
+const pad = (v, w) => String(v).padEnd(w);
+const padL = (v, w) => String(v).padStart(w);
+
+function printTable(rows) {
+  const cols = [
+    ["world", 10, r => r.world], ["strategy", 11, r => r.strategy], ["diff", 7, r => r.difficulty],
+    ["score", 6, r => score(r).total], ["dev", 4, r => r.devFinal], ["+dev", 5, r => r.devGrowthTail],
+    ["army", 5, r => r.armyFinal], ["wrk", 4, r => r.workersFinal], ["bank", 7, r => r.bankedPeak],
+    ["waves", 6, r => r.waves], ["idle%", 6, r => r.idleRichFrac], ["hostIdle", 9, r => r.hostileIdleFrac],
+  ];
+  console.log(cols.map(([h, w]) => pad(h, w)).join(""));
+  console.log(cols.map(([, w]) => "-".repeat(w - 1) + " ").join(""));
+  for (const r of rows) console.log(cols.map(([, w, f]) => pad(f(r), w)).join(""));
+}
+
+function printFindings(rows) {
+  console.log("\nHealth checks (a row here is a reproducible defect, not a style note):");
+  let any = false;
+  for (const c of CHECKS) {
+    const hits = rows.filter(c.hit);
+    if (!hits.length) { console.log(`  ok    ${pad(c.id, 20)} —`); continue; }
+    any = true;
+    console.log(`  FIRES ${pad(c.id, 20)} ${hits.length}/${rows.length} runs`);
+    console.log(`        ${c.why}`);
+    console.log(`        ${hits.slice(0, 6).map(r => `${r.world}/${r.strategy}/${r.difficulty}`).join("  ")}`
+      + (hits.length > 6 ? `  …+${hits.length - 6}` : ""));
+  }
+  if (!any) console.log("  (clean)");
+}
+
+const CMDS = {
+  probe(args) {
+    const base = baseConfig(args);
+    const cfg = {
+      ...base,
+      world: args.world || "ferros",
+      strategy: args.strategy || "default",
+      difficulty: args.difficulty || "medium",
+    };
+    const r = run({ ...cfg, seed: runSeed(base.seedBase, cfg.world, cfg.strategy, cfg.difficulty, 0) });
+    console.log(`${cfg.world} · ${cfg.strategy} · ${cfg.difficulty} · vs ${OPPONENTS[cfg.opponent].desc}`);
+    console.log("\ntime  wrk army  dev bldg   banked  waves stance  supplyFree  idleRax");
+    for (const c of r.curve)
+      console.log(`${padL(Math.round(c.t / 60) + "m", 4)} ${padL(c.workers, 4)} ${padL(c.army, 3)} `
+        + `${padL(c.dev, 4)} ${padL(c.buildings, 4)} ${padL(c.banked, 8)} ${padL(c.waves, 6)} `
+        + `${padL(c.stance, 6)} ${padL(c.supplyFree, 11)} ${padL(c.idleRax, 8)}`);
+    const sc = score(r);
+    console.log(`\nscore ${sc.total}  ` + Object.entries(sc.parts).map(([k, v]) => `${k} ${v.toFixed(2)}`).join("  "));
+    printFindings([r]);
+  },
+
+  sweep(args) {
+    const rows = runMatrix(args, {
+      worlds: list(args.worlds, ["korrath", "ferros", "vesper", "kybernet"]),
+      strategies: list(args.strategies, Object.keys(STRATEGIES)),
+      difficulties: list(args.difficulties, ["medium"]),
+      seeds: num(args.seeds, 1),
+    });
+    printTable(rows);
+    const mean = rows.reduce((a, r) => a + score(r).total, 0) / rows.length;
+    console.log(`\nmean score ${mean.toFixed(3)} over ${rows.length} runs`);
+    printFindings(rows);
+    if (args.json) {
+      // Summary rows only unless --full: a saved sweep is meant to be read (by you or by
+      // Claude) and diffed against the next one, and the per-sample curve buries the
+      // handful of numbers a decision actually turns on.
+      const out = rows.map(({ curve, ...r }) => ({ ...r, score: score(r), ...(args.full === "true" ? { curve } : {}) }));
+      writeFileSync(args.json, JSON.stringify(out, null, 1));
+      console.log(`\nwrote ${args.json}`);
+    }
+    if (args.csv) {
+      const keys = Object.keys(summarise(rows[0].curve));
+      const head = ["world", "strategy", "difficulty", "seed", "score", ...keys];
+      const body = rows.map(r => [r.world, r.strategy, r.difficulty, r.seed, score(r).total, ...keys.map(k => r[k])].join(","));
+      writeFileSync(args.csv, [head.join(","), ...body].join("\n") + "\n");
+      console.log(`wrote ${args.csv}`);
+    }
+  },
+
+  // A/B two saved sweeps (or a sweep against an overrides file run inline). Prints the
+  // per-configuration delta, because a mean that moved could be one world moving a lot.
+  compare(args) {
+    const load = p => JSON.parse(readFileSync(p, "utf8"));
+    const a = load(args.baseline), b = load(args.candidate);
+    const key = r => `${r.world}/${r.strategy}/${r.difficulty}/${r.seed}`;
+    const bm = new Map(b.map(r => [key(r), r]));
+    console.log(pad("configuration", 34) + pad("base", 8) + pad("cand", 8) + "delta");
+    let sa = 0, sb = 0, n = 0;
+    for (const r of a) {
+      const o = bm.get(key(r));
+      if (!o) continue;
+      const x = r.score.total, y = o.score.total;
+      sa += x; sb += y; n++;
+      const d = +(y - x).toFixed(3);
+      console.log(pad(key(r), 34) + pad(x.toFixed(3), 8) + pad(y.toFixed(3), 8) + (d > 0 ? "+" : "") + d);
+    }
+    if (!n) { console.log("no matching configurations — the two sweeps must cover the same matrix"); return; }
+    console.log(`\nmean ${(sa / n).toFixed(3)} -> ${(sb / n).toFixed(3)}  `
+      + `(${sb > sa ? "+" : ""}${((sb - sa) / n).toFixed(3)} per configuration, n=${n})`);
+  },
+
+  // Coordinate search over a strategy's numeric dials. Deliberately the simplest thing that
+  // works: a deterministic scan of each dial in turn, keeping an improvement. It's here to
+  // make the search REPRODUCIBLE and cheap to reason about — the interesting judgement is in
+  // which dials to open and what the objective is, and both of those are yours (or Claude's).
+  search(args) {
+    const name = args.strategy || "default";
+    const dials = list(args.dials, []).map(d => {
+      const [k, range] = d.split("=");
+      const [lo, hi] = String(range).split(":").map(Number);
+      return { k, lo, hi };
+    });
+    if (!dials.length) { console.log("--dials 'attackTimeoutMult=0.3:1,garrisonMult=0:1'"); return; }
+    const worlds = list(args.worlds, ["korrath", "ferros", "vesper"]);
+    const difficulties = list(args.difficulties, ["medium"]);
+    const steps = num(args.steps, 4);
+    const base = { ...(STRATEGIES[name] || {}) };
+    const evaluate = row => {
+      applyOverrides({ strategies: { [`${name}__lab`]: row } });
+      const rows = runMatrix(args, { worlds, strategies: [`${name}__lab`], difficulties, seeds: num(args.seeds, 1) });
+      return { mean: rows.reduce((a, r) => a + score(r).total, 0) / rows.length, rows };
+    };
+    let best = { ...base }, bestScore = evaluate(best).mean;
+    console.log(`start ${name} -> ${bestScore.toFixed(3)}  ${JSON.stringify(pickDials(best, dials))}`);
+    for (const d of dials) {
+      for (let i = 0; i <= steps; i++) {
+        const v = +(d.lo + (d.hi - d.lo) * (i / steps)).toFixed(3);
+        const cand = { ...best, [d.k]: v };
+        const { mean } = evaluate(cand);
+        const better = mean > bestScore + 1e-9;
+        console.log(`  ${pad(d.k + "=" + v, 32)} ${mean.toFixed(3)}${better ? "  *" : ""}`);
+        if (better) { best = cand; bestScore = mean; }
+      }
+    }
+    console.log(`\nbest ${bestScore.toFixed(3)}  ${JSON.stringify(pickDials(best, dials), null, 1)}`);
+    console.log("\nThis is a LOCAL search on a noisy objective — re-run the winner through "
+      + "`sweep --seeds 3` on the full roster before believing it.");
+  },
+
+  check(args) {
+    const rows = runMatrix(args, {
+      worlds: list(args.worlds, WORLDS),
+      strategies: list(args.strategies, Object.keys(STRATEGIES)),
+      difficulties: list(args.difficulties, ["medium"]),
+      seeds: 1,
+    });
+    printTable(rows);
+    const mean = rows.reduce((a, r) => a + score(r).total, 0) / rows.length;
+    console.log(`\nmean score ${mean.toFixed(3)} over ${rows.length} runs`);
+    printFindings(rows);
+    if (args["exit-code"] === "true" && CHECKS.some(c => rows.some(c.hit))) process.exitCode = 1;
+  },
+};
+
+const USAGE = `AI LAB — a headless bench for the Odyssey opponent.
+
+  node tools/ailab.js probe   [--world ferros] [--strategy default] [--difficulty medium]
+                              [--opponent passive] [--minutes 40] [--sample 5]
+  node tools/ailab.js sweep   [--worlds a,b] [--strategies a,b] [--difficulties a,b]
+                              [--seeds 3] [--minutes 40] [--json out.json] [--csv out.csv] [--full]
+  node tools/ailab.js compare --baseline base.json --candidate cand.json
+  node tools/ailab.js search  --strategy aggressive --dials 'attackTimeoutMult=0.3:1,garrisonMult=0:1'
+                              [--steps 4] [--worlds a,b]
+  node tools/ailab.js check   [--worlds a,b] [--minutes 60] [--exit-code]
+
+Common flags
+  --overrides f.json   inject candidate rows into the AI tables before running:
+                       { "strategies":   { "swarm":  { "armyAttackSizeMult": 0.5 } },
+                         "archetypes":   { "rusher": { "odyssey": { "workerTarget": 9 } } },
+                         "difficulties": { "hard":   { "workerTargetMult": 1.4 } } }
+  --seed N             base seed (default 1) — every row is reproducible from it`;
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const cmd = args._[0];
+  if (!cmd || !CMDS[cmd]) {
+    console.log(USAGE);
+    console.log(`\nworlds: ${WORLDS.join(", ")}`);
+    console.log(`strategies: ${Object.keys(STRATEGIES).join(", ")}`);
+    console.log(`opponents: ${Object.entries(OPPONENTS).map(([k, v]) => `${k} (${v.desc})`).join("\n            ")}`);
+    return;
+  }
+  if (args.overrides) applyOverrides(JSON.parse(readFileSync(args.overrides, "utf8")));
+  const t0 = process.hrtime.bigint();   // deterministic-exempt: wall clock is for the operator's benefit only, never read by the sim
+  CMDS[cmd](args);
+  console.log(`\n(${Number(process.hrtime.bigint() - t0) / 1e9 | 0}s)`);
+}
+
+// Only run the CLI when invoked directly, so a test can import run/score/CHECKS.
+if (process.argv[1] && new URL(import.meta.url).pathname === process.argv[1]) main(process.argv.slice(2));
+
+export { run, labWorld, sample, summarise, OPPONENTS, WORLDS };