feat(SAC_LSTM_Bot): training harness (#49)

sac_train.sh orchestrates chunked self-play via tools/training_runner/
RunTraining.java: weighted opponent sampling per chunk, deterministic
eval (SACLSTM_EVAL_MODE=1) every N chunks with win-rate tracking, best
checkpoint (weights/sac_best.zip) by eval score, crash-restart loop on
the runner's liveness detection.

Supporting changes:
- integration.nim: opponentKey() keys the NewBattle buffer-clear rule on
  getBotName(id) with numeric-id fallback (#49 Q14 follow-up);
  bumpRoundCounter() emits the per-round liveness signal.
- SAC_LSTM_Bot.nim: onRoundEnded -> bumpRoundCounter().
- RunTraining.java: BOT_NAME env parameterizes result matching
  (default PPO_Bot, unchanged behavior for PPO).
- Launch packaging: root SAC_LSTM_Bot.json + .sh for the booter;
  src json name aligned to 'SAC_LSTM_Bot' so self-reported identity
  matches the booted identity (mismatch = runner connect timeout).

SAC_LSTM_Bot/src/SAC_LSTM_Bot.json

@@ -1,8 +1,8 @@
 {
-  "name": "Recurrent Royalty",
+  "name": "SAC_LSTM_Bot",
   "version": "0.1.0",
   "authors": ["Davide Cappellini"],
-  "description": "SAC+LSTM Tank Royale bot — skeleton with radar lock",
+  "description": "SAC+LSTM Tank Royale bot — self-reported identity; MUST match the name in ../SAC_LSTM_Bot.json (booter identity) or the training runner never sees this bot join",
   "homepage": "",
   "countryCodes": ["IT"],
   "gameTypes": ["classic", "melee", "1v1"],

SAC_LSTM_Bot/src/SAC_LSTM_Bot.nim

@@ -144,8 +144,9 @@ method onScannedBot*(bot: SacBot, e: ScannedBotEvent) =
   bot.enemy.energy = e.energy
   bot.hasContact = true
   bot.ticksSinceScan = 0
-  # Q12b/Q14: one NewBattle per battle, numeric scannedBotId
-  # ponytail: name-based opponent identity deferred to #49 (protocol has no names).
+  # Q12b/Q14+#49: one NewBattle per battle, numeric scannedBotId. Identity is
+  # keyed on getBotName(id) training-side (integration.opponentKey), numeric
+  # fallback in the pre-BotListUpdate window.
   if not bot.newBattleSent:
     bot.newBattleSent = true
     discard sendTrainingMsg(TrainingMsg(kind: tmkNewBattle, enemyId: e.scannedBotId))
@@ -169,6 +170,11 @@ method onGameAborted*(bot: SacBot) =
   bot.hasLastTrans = false
   bot.dmgDealt = 0; bot.dmgTaken = 0; bot.wastedPower = 0; bot.wallHits = 0
 
+method onRoundEnded*(bot: SacBot, e: RoundEndedEventForBot) =
+  ## Harness liveness signal (#49): RunTraining.java watches round_counter.txt
+  ## and aborts the battle if it freezes (dead bot process). Main thread.
+  bumpRoundCounter()
+
 method onGameEnded*(bot: SacBot, e: GameEndedEventForBot) =
   ## Battle end -> terminal transition with done=true. Main thread; the API has
   ## joined the bot thread before this fires, so these plain fields are quiescent.

SAC_LSTM_Bot/src/SAC_LSTM_Bot/integration.nim

@@ -13,6 +13,7 @@
 
 import arraymancer except Linear
 import std/[locks, os, math, random, strutils]
+import tankroyale_botapi   # getBotName (#49 name-based opponent identity)
 import SAC_LSTM_Bot/network
 import SAC_LSTM_Bot/state        # STATE_DIM
 import SAC_LSTM_Bot/actions      # ACTION_DIM
@@ -38,6 +39,31 @@ proc getWeightsPath*(): string =
   getEnv("SACLSTM_WEIGHTS_PATH",
     currentSourcePath().parentDir / "weights" / "sac_latest.zip")
 
+proc opponentKey*(enemyId: int): string =
+  ## Q14 follow-up (#49): name-based opponent identity from the v1.0.1
+  ## BotListUpdate table; numeric-id fallback for the window before the first
+  ## update arrives (getBotName still returns "" then). Called on the training
+  ## thread — the lookup is lock-guarded in the API, no cross-thread refs.
+  let name = getBotName(enemyId)
+  if name.len > 0: name else: $enemyId
+
+proc bumpRoundCounter*() =
+  ## Liveness signal for tools/training_runner/RunTraining.java (#49): one
+  ## increment per round end; the runner aborts when it freezes (dead bot).
+  # ponytail: non-atomic read-modify-write; single writer (main thread) and the
+  # runner re-polls every 500ms with multi-round tolerance, torn reads self-heal.
+  let p = getWeightsPath().parentDir / "round_counter.txt"
+  var n = 0
+  try:
+    n = parseInt(readFile(p).strip())
+  except CatchableError:
+    discard   # absent/garbage -> start at 1
+  try:
+    createDir(p.parentDir)
+    writeFile(p, $(n + 1))
+  except CatchableError:
+    discard   # counter is best-effort liveness; never kill an event handler
+
 # ── Channel message (plain data only) ────────────────────────────────────────
 
 type
@@ -200,7 +226,7 @@ type
   TrainState* = object
     trainer*:    SACTrainer
     buf*:        ReplayBuffer
-    lastEnemyId*: int
+    lastEnemyKey*: string   # opponent identity key (#49 name-based, Q14)
     stepCount*:  int
     nextSave*:   int
 
@@ -227,7 +253,7 @@ proc trainerFromFull*(initial: FullSnap): SACTrainer =
 proc initTrainState*(initial: FullSnap): TrainState =
   result.trainer    = trainerFromFull(initial)
   result.buf        = newReplayBuffer(getBufferCapacity(), STATE_DIM, ACTION_DIM)
-  result.lastEnemyId = -1
+  result.lastEnemyKey = ""
   result.nextSave   = getSaveInterval()
 
 proc handleTrainingMsg*(st: var TrainState; msg: TrainingMsg): bool =
@@ -243,9 +269,11 @@ proc handleTrainingMsg*(st: var TrainState; msg: TrainingMsg): bool =
       done:      msg.done))
   of tmkNewBattle:
     # Q12a: keep the buffer if the opponent is unchanged, clear otherwise.
-    if msg.enemyId != st.lastEnemyId:
+    # Identity keyed on NAME (#49); numeric-id fallback pre-BotListUpdate.
+    let key = opponentKey(msg.enemyId)
+    if key != st.lastEnemyKey:
       st.buf.clear()
-      st.lastEnemyId = msg.enemyId
+      st.lastEnemyKey = key
   of tmkShutdown:
     return false
   true