Align local Bazel hydration with CI builds (#7084)

.github/workflows/eagle_build.yml

@@ -12,6 +12,7 @@ on:
       - 'BUILD.bazel'
       - '.bazelrc'
       - 'ci/github_actions/ensure_bazel_installed.sh'
+      - 'scripts/build_eagle_ci.sh'
       - '.github/workflows/eagle_build.yml'
 
 concurrency:
@@ -51,4 +52,4 @@ jobs:
       - name: Ensure Bazel installed
         run: ./ci/github_actions/ensure_bazel_installed.sh
       - name: Build Eagle server
-        run: bazel build //src/main/scala/net/eagle0/eagle:eagle_server
+        run: ./scripts/build_eagle_ci.sh

.github/workflows/shardok_build.yml

@@ -13,6 +13,7 @@ on:
       - 'BUILD.bazel'
       - '.bazelrc'
       - 'ci/github_actions/ensure_bazel_installed.sh'
+      - 'scripts/build_shardok_ci.sh'
       - '.github/workflows/shardok_build.yml'
 
 concurrency:
@@ -52,4 +53,4 @@ jobs:
       - name: Ensure Bazel installed
         run: ./ci/github_actions/ensure_bazel_installed.sh
       - name: Build Shardok server
-        run: bazel build -c opt //src/main/cpp/net/eagle0/shardok:shardok-server
+        run: ./scripts/build_shardok_ci.sh

AGENTS.md

@@ -105,14 +105,14 @@ Unity Client ↔ Eagle (gRPC streaming) ↔ Shardok (internal gRPC)
 ### Building
 
 ```bash
-# Build Eagle server (Scala strategic layer)
-bazel build //src/main/scala/net/eagle0/eagle:eagle_server_deploy.jar
+# Build Eagle server using the same target as GitHub Actions
+./scripts/build_eagle_ci.sh
 
-# Build Shardok server (C++ tactical layer)
-bazel build -c opt //src/main/cpp/net/eagle0/shardok:shardok-server
+# Build Shardok server using the same target and flags as GitHub Actions
+./scripts/build_shardok_ci.sh
 
-# Shardok server includes both AI algorithms
-bazel build //src/main/cpp/net/eagle0/shardok:shardok-server
+# Warm the remote cache for the main GitHub Actions Bazel builds
+./scripts/hydrate_bazel_remote_cache.sh
 
 # Build Unity/C# client
 ./scripts/build_protos.sh         # Protocol buffer generation for Unity
@@ -165,6 +165,19 @@ bazel run gazelle              # Update Go build files
 
 The pre-commit hook runs gazelle but only checks if it succeeds - it does NOT verify the BUILD files are in canonical format. The `gazelle_test` will fail if deps are not alphabetically sorted. **Always run gazelle manually after BUILD file changes.**
 
+### Bazel Cache Hydration
+
+When making changes that will trigger GitHub Actions Bazel builds, run the matching CI script instead of hand-writing
+`bazel build` commands. The scripts keep local cache hydration aligned with CI targets, compilation modes, and flags:
+
+```bash
+./scripts/build_eagle_ci.sh
+./scripts/build_shardok_ci.sh
+./scripts/hydrate_bazel_remote_cache.sh
+```
+
+Use direct `bazel build` commands only for targeted debugging where CI cache hydration is not the goal.
+
 ### Code Formatting
 
 ```bash
@@ -225,7 +238,7 @@ ShardokAIClient client(playerId, isDefender, hexMap, settings, AIAlgorithmType::
 
 ```bash
 # Build the server (includes both AI algorithms)
-bazel build //src/main/cpp/net/eagle0/shardok:shardok-server
+./scripts/build_shardok_ci.sh
 
 # Test both algorithms
 bazel test //src/test/cpp/net/eagle0/shardok/ai:ai_iterative_deepening_test

scripts/build_eagle_ci.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+bazel build //src/main/scala/net/eagle0/eagle:eagle_server

scripts/build_shardok_ci.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+bazel build -c opt //src/main/cpp/net/eagle0/shardok:shardok-server

scripts/check_bazel_remote_cache_parity.sh

@@ -26,24 +26,18 @@ case "$mode" in
         ;;
 esac
 
-targets=("$@")
-if [ "${#targets[@]}" -eq 0 ]; then
-    targets=(
-        "//src/main/cpp/net/eagle0/shardok/library:engine"
-        "//src/main/scala/net/eagle0/eagle:eagle_server"
-    )
-fi
-
 tmp_root="${RUNNER_TEMP:-/private/tmp}"
 run_id="${GITHUB_RUN_ID:-local}-$$"
 output_base="${tmp_root%/}/eagle0-cache-parity-${mode}-${run_id}"
 
 echo "Mode: $mode"
 echo "Output base: $output_base"
-echo "Targets:"
-printf '  %s\n' "${targets[@]}"
 
-bazel_args=(
+run_bazel() {
+    echo "Bazel args:"
+    printf '  %s\n' "$@"
+
+    local bazel_args=(
         "--output_base=$output_base"
         "build"
         "--remote_download_all"
@@ -57,4 +51,13 @@ if [ "$mode" = "verify" ]; then
         )
     fi
 
-bazel "${bazel_args[@]}" "${targets[@]}"
+    bazel "${bazel_args[@]}" "$@"
+}
+
+if [ "$#" -gt 0 ]; then
+    run_bazel "$@"
+    exit 0
+fi
+
+run_bazel //src/main/scala/net/eagle0/eagle:eagle_server
+run_bazel -c opt //src/main/cpp/net/eagle0/shardok:shardok-server

scripts/hydrate_bazel_remote_cache.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+scripts/build_eagle_ci.sh
+scripts/build_shardok_ci.sh