Headless bot fleet: automation client, movement resilience, and shared client fixes

.gitignore

@@ -86,6 +86,13 @@ imgui.ini
 config.ini
 config.json
 .env
+client/
+tools/.env
+tools/headless_client/settings.json
+tools/bot_fleet_manager/fleet.settings.json
+tools/bot_fleet_manager/runtime/
+tools/provisioning/*.local.json
+tools/provisioning/roster.json
 
 # Runtime cache (floor heights, etc.)
 cache/
@@ -106,9 +113,11 @@ asset_pipeline/
 # Local texture dumps / extracted art should never be committed
 assets/textures/
 node_modules/
+vcpkg_installed/
 
 # Python cache artifacts
 tools/__pycache__/
+**/__pycache__/
 *.pyc
 
 # World editor output: scaffolded/exported zones and per-user ImGui layout

CLAUDE.md

@@ -0,0 +1,95 @@
+# WoWee repo notes for Claude
+
+## Two remotes, two audiences
+
+- `origin` (`paleophyte/WoWee`) - this fork. Headless bot-fleet work
+  (`tools/headless_client/`, `tools/bot_fleet_manager/`, `tools/world_db_query/`,
+  `tools/provisioning/`, `BOT_PLAN.md`, the `WOWEE_HEADLESS`/`WOWEE_HEADLESS_DEFAULT`
+  build machinery) lives here only - none of it exists upstream, so it can't
+  meaningfully be split out or PR'd there.
+- `upstream` (`Kelsidavis/WoWee`) - the original project. Only bug fixes and
+  improvements to code that exists in *both* trees (`src/game/`, `include/game/`,
+  `src/core/`, `src/ui/`, `src/rendering/`, etc. - the GUI/shared client) belong here.
+
+This file itself is fork-specific context. It originally lived only on
+`feat/headless-bot-fleet` on the assumption `master` would stay a clean
+upstream mirror - as of 2026-07-13, `origin/master` (this fork's master, not
+upstream's) had the entire `feat/headless-bot-fleet` branch merged into it
+directly (PR #4), so it now permanently carries the full headless-bot-fleet
+content, this file included. That's fine on its own terms (headless work
+living only in this fork was always the intent - see above), but it means
+**`origin/master`/local `master` can no longer be assumed clean for cutting
+shared-code fix branches**. Use `upstream/master` (fetched fresh via
+`git fetch upstream`) as the base for those instead - see below.
+
+## Don't build the `wowee` GUI target on this machine
+
+This is a VM with no GUI testing use - the user pulls this repo to their Mac
+or Windows laptop (whichever matches the platform they want to test) and
+builds/runs `wowee` there. `wowee`'s compile time is significant, so treat
+that cycle as expensive and avoid spending it here by default.
+
+- Default to building only `wowee_headless` to verify shared-code changes
+  compile - that's almost always sufficient, since `wowee` and
+  `wowee_headless` share the same source for anything outside
+  `tools/headless_client/` and `WOWEE_HEADLESS`-gated branches.
+- CI (GitHub Actions, `Build (windows-x86-64)`/`(x86-64)`/`(macOS arm64)`/etc.)
+  already builds and validates `wowee` for every PR - that's the normal way
+  a `wowee`-side compile error gets caught, not a local build here.
+- If something seems like it could *specifically* require compiling `wowee`
+  locally to prove (e.g. a GUI-only code path CI can't exercise, or CI itself
+  is failing in a way that needs local repro) - stop and ask the user for
+  confirmation first, explaining exactly why the headless-only build or CI
+  isn't enough for this specific case. Don't just build it "to be thorough."
+
+## When fixing a bug in shared code
+
+If a fix touches a file that also exists upstream (not just something under
+`tools/headless_client/` or gated behind `WOWEE_HEADLESS`), cut a small,
+focused branch for it off **`upstream/master`** (not local/`origin` `master`
+- see the note above about why that's no longer a clean base) *in addition
+to* whatever work is happening on this feature branch - don't let it get
+stuck waiting for a future retroactive extraction. Precedent:
+`fix/area-trigger-dbc-load-race` was done this way and is already merged
+upstream as PR #91.
+
+1. `git fetch upstream` and diff the target function/file against
+   `upstream/master` to confirm the bug is still actually there (not already
+   fixed independently) - don't assume the local history summary is still
+   accurate.
+2. `git checkout -b fix/<short-name> upstream/master` (or `feat/<short-name>`
+   for a genuine improvement, not a bug fix).
+3. Apply *only* the shared-code hunks - if the same commit on this branch
+   also touched a headless-only call site (e.g. a new HTTP endpoint in
+   `tools/headless_client/main.cpp` that exercises the fix), leave that part
+   out. Check `git diff upstream/master feat/headless-bot-fleet -- <file>`
+   first; several shared files have accumulated unrelated headless-only
+   hunks (env-var gating, new headless-only methods) mixed in from other
+   work, so don't blindly `git checkout <branch> -- <file>` a whole file
+   without checking what's actually in its diff.
+4. Build `wowee_headless` against the new branch before committing (see
+   "Don't build the `wowee` GUI target on this machine" above for why not
+   both - CI covers `wowee` once pushed).
+5. Push and open a PR against `paleophyte/WoWee` `master` first - never
+   open the upstream PR before this one exists and its CI is clean.
+6. Once that PR's local CI is green, `git fetch upstream` again and check
+   `git log --oneline <fix-branch>..upstream/master`. This confirms the fix
+   branch is still current *at the moment of forwarding*, not just when it
+   was cut - upstream moves fast enough that new commits can land during
+   the CI run itself.
+   - **Not behind**: open the PR directly against `Kelsidavis/WoWee`
+     `master` - this is pre-authorized, no need to check back first.
+   - **Behind, and the new upstream commits don't touch this fix's files**:
+     open the PR anyway: unrelated upstream churn isn't a reason to hold it.
+   - **Behind, and a new upstream commit touches the same function/file**:
+     do not open the PR yet. Re-run the full sync cycle first - merge fresh
+     `upstream/master` into the shared-code fix branch (and into
+     `feat/headless-bot-fleet` separately, if it also carries this fix),
+     resolve conflicts (favor whichever side has real, currently-working
+     logic over a duplicate/dead code path - see the `updateTaxiAndMountState()`
+     precedent from 2026-07-12 for the reasoning to apply), rebuild
+     `wowee_headless`, push, and wait for CI to go green again before
+     re-checking upstream and opening the PR.
+
+Keep each branch to one logical fix - small and reviewable, matching the
+PR #91 precedent, not one giant "everything shared" branch.

CMakeLists.txt

@@ -31,6 +31,7 @@ option(WOWEE_ENABLE_TRACY "Enable Tracy profiler instrumentation" OFF)
 option(WOWEE_ENABLE_AMD_FSR2 "Enable AMD FidelityFX FSR2 backend when SDK is present" ON)
 option(WOWEE_ENABLE_AMD_FSR3_FRAMEGEN "Enable AMD FidelityFX SDK FSR3 frame generation interface probe when SDK is present" ON)
 option(WOWEE_BUILD_AMD_FSR3_RUNTIME "Build native AMD FidelityFX VK runtime (Path A) from extern/FidelityFX-SDK/Kits" ON)
+set(WOWEE_MANGOS_TBC_DIR "C:/Users/admin/code/mangos-tbc" CACHE PATH "Optional CMaNGOS TBC checkout used to build mmap_path_query")
 
 # AMD FidelityFX FSR2 SDK detection (drop-in under extern/FidelityFX-FSR2)
 set(WOWEE_AMD_FSR2_DIR ${CMAKE_SOURCE_DIR}/extern/FidelityFX-FSR2)
@@ -507,6 +508,7 @@ set(WOWEE_SOURCES
     src/core/window.cpp
     src/core/input.cpp
     src/core/logger.cpp
+    src/core/crash_diagnostics.cpp
     src/core/memory_monitor.cpp
 
     # Math
@@ -1463,6 +1465,106 @@ set_target_properties(auth_login_probe PROPERTIES
 )
 install(TARGETS auth_login_probe RUNTIME DESTINATION bin)
 
+set(WOWEE_HEADLESS_SOURCES ${WOWEE_SOURCES})
+list(REMOVE_ITEM WOWEE_HEADLESS_SOURCES src/main.cpp)
+add_executable(wowee_headless
+    tools/headless_client/main.cpp
+    ${WOWEE_HEADLESS_SOURCES}
+)
+target_compile_definitions(wowee_headless PRIVATE WOWEE_HEADLESS_DEFAULT=1)
+if(TARGET opcodes-generate)
+    add_dependencies(wowee_headless opcodes-generate)
+endif()
+add_dependencies(wowee_headless wowee_version)
+target_include_directories(wowee_headless PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/include
+    ${CMAKE_CURRENT_SOURCE_DIR}/src
+    ${CMAKE_BINARY_DIR}/generated
+)
+target_include_directories(wowee_headless SYSTEM PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/extern
+    ${CMAKE_CURRENT_SOURCE_DIR}/extern/vk-bootstrap/src
+)
+if(HAVE_FFMPEG)
+    target_compile_definitions(wowee_headless PRIVATE HAVE_FFMPEG)
+    target_include_directories(wowee_headless PRIVATE ${FFMPEG_INCLUDE_DIRS})
+    target_link_libraries(wowee_headless PRIVATE ${FFMPEG_LIBRARIES})
+    if(FFMPEG_LIBRARY_DIRS)
+        target_link_directories(wowee_headless PRIVATE ${FFMPEG_LIBRARY_DIRS})
+    endif()
+endif()
+target_link_libraries(wowee_headless PRIVATE
+    SDL2::SDL2
+    Vulkan::Vulkan
+    OpenSSL::SSL
+    OpenSSL::Crypto
+    Threads::Threads
+    ZLIB::ZLIB
+    lua51
+    ${CMAKE_DL_LIBS}
+)
+if(UNIX AND NOT APPLE)
+    target_link_libraries(wowee_headless PRIVATE X11)
+endif()
+if(WIN32)
+    target_link_libraries(wowee_headless PRIVATE ws2_32)
+endif()
+if(TARGET imgui)
+    target_link_libraries(wowee_headless PRIVATE imgui)
+endif()
+if(TARGET vk-bootstrap)
+    target_link_libraries(wowee_headless PRIVATE vk-bootstrap)
+endif()
+if(TARGET wowee_fsr2_amd_vk)
+    target_link_libraries(wowee_headless PRIVATE wowee_fsr2_amd_vk)
+endif()
+if(TARGET wowee_fsr3_framegen_amd_vk_probe)
+    target_link_libraries(wowee_headless PRIVATE wowee_fsr3_framegen_amd_vk_probe)
+endif()
+if(HAVE_UNICORN)
+    target_link_libraries(wowee_headless PRIVATE ${UNICORN_LIBRARY})
+    target_include_directories(wowee_headless PRIVATE ${UNICORN_INCLUDE_DIR})
+    target_compile_definitions(wowee_headless PRIVATE HAVE_UNICORN)
+endif()
+if(TARGET glm::glm)
+    target_link_libraries(wowee_headless PRIVATE glm::glm)
+elseif(glm_FOUND)
+    target_include_directories(wowee_headless PRIVATE ${GLM_INCLUDE_DIRS})
+endif()
+set_target_properties(wowee_headless PROPERTIES
+    RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin
+)
+install(TARGETS wowee_headless RUNTIME DESTINATION bin)
+
+# ---- Tool: mmap_path_query (CMaNGOS mmap/Detour JSON path helper) ----
+set(WOWEE_DETOUR_DIR "${WOWEE_MANGOS_TBC_DIR}/dep/recastnavigation/Detour")
+if(EXISTS "${WOWEE_DETOUR_DIR}/Include/DetourNavMesh.h")
+    add_executable(mmap_path_query
+        tools/pathfinding_service/mmap_path_query.cpp
+        ${WOWEE_DETOUR_DIR}/Source/DetourAlloc.cpp
+        ${WOWEE_DETOUR_DIR}/Source/DetourAssert.cpp
+        ${WOWEE_DETOUR_DIR}/Source/DetourCommon.cpp
+        ${WOWEE_DETOUR_DIR}/Source/DetourNavMesh.cpp
+        ${WOWEE_DETOUR_DIR}/Source/DetourNavMeshBuilder.cpp
+        ${WOWEE_DETOUR_DIR}/Source/DetourNavMeshQuery.cpp
+        ${WOWEE_DETOUR_DIR}/Source/DetourNode.cpp
+    )
+    target_include_directories(mmap_path_query PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/extern
+        ${WOWEE_DETOUR_DIR}/Include
+    )
+    target_compile_definitions(mmap_path_query PRIVATE DT_POLYREF64)
+    set_target_properties(mmap_path_query PROPERTIES
+        CXX_STANDARD 17
+        CXX_STANDARD_REQUIRED ON
+        RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin
+    )
+    install(TARGETS mmap_path_query RUNTIME DESTINATION bin)
+    message(STATUS "  mmap_path_query tool: ENABLED (${WOWEE_MANGOS_TBC_DIR})")
+else()
+    message(STATUS "  mmap_path_query tool: DISABLED (set WOWEE_MANGOS_TBC_DIR to a CMaNGOS TBC checkout)")
+endif()
+
 # ---- Tool: blp_convert (BLP ↔ PNG) ----
 add_executable(blp_convert
     tools/blp_convert/main.cpp

include/core/crash_diagnostics.hpp

@@ -0,0 +1,17 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+namespace wowee::core {
+
+void installCrashDiagnostics(const char* processLabel);
+void setCrashBreadcrumb(const char* phase,
+                        uint16_t wireOpcode,
+                        const char* logicalOpcode,
+                        std::size_t packetSize,
+                        std::size_t readPos,
+                        int worldState);
+void setCrashNote(const char* note);
+
+} // namespace wowee::core

include/game/entity_controller.hpp

@@ -35,6 +35,9 @@ class EntityController {
     void queryPlayerName(uint64_t guid);
     void queryCreatureInfo(uint32_t entry, uint64_t guid);
     void queryGameObjectInfo(uint32_t entry, uint64_t guid);
+    void cachePlayerName(uint64_t guid, const std::string& name) {
+        if (guid != 0 && !name.empty()) playerNameCache[guid] = name;
+    }
     std::string getCachedPlayerName(uint64_t guid) const;
     std::string getCachedCreatureName(uint32_t entry) const;
     void invalidatePlayerName(uint64_t guid) { playerNameCache.erase(guid); }

include/game/faction_hostility.hpp

@@ -16,9 +16,11 @@ class GameHandler;
 // GameHandler::isHostileFaction() defaults an unrecognized faction template
 // ID to hostile=true (a reasonable default once the map is actually
 // populated, since anything left out by the DBC-driven loop below is
-// genuinely unusual). Call this once per session, as soon as playerRace is
-// known and the asset manager is initialized, or every faction template
-// will fall through to that hostile default.
+// genuinely unusual). The headless client never called this, so the map
+// stayed permanently empty and *everything* read as hostile - live-observed
+// at Menethil Harbor as ~20 false-positive "threats" including town guards,
+// friendly party bots, and a critter. Call this once per session, as soon
+// as playerRace is known and the asset manager is initialized.
 void buildFactionHostilityMap(pipeline::AssetManager& assetManager, GameHandler& gameHandler, uint8_t playerRace);
 
 } // namespace game

include/game/game_handler.hpp

@@ -495,6 +495,7 @@ class GameHandler : public IConnectionState,
     // Instance difficulty
     void sendSetDifficulty(uint32_t difficulty);
     bool  isLoggingOut() const;
+    bool  isLogoutComplete() const;
     float getLogoutCountdown() const;
 
     // Stand state
@@ -648,6 +649,9 @@ class GameHandler : public IConnectionState,
     void queryPlayerName(uint64_t guid);
     void queryCreatureInfo(uint32_t entry, uint64_t guid);
     void queryGameObjectInfo(uint32_t entry, uint64_t guid);
+    void cachePlayerName(uint64_t guid, const std::string& name) {
+        entityController_->cachePlayerName(guid, name);
+    }
     const GameObjectQueryResponseData* getCachedGameObjectInfo(uint32_t entry) const {
         return entityController_->getCachedGameObjectInfo(entry);
     }
@@ -1192,6 +1196,7 @@ class GameHandler : public IConnectionState,
     bool hasServerTransportUpdate(uint64_t guid) const { return entityController_->hasServerTransportUpdate(guid); }
     glm::vec3 getComposedWorldPosition();  // Compose transport transform * local offset
     TransportManager* getTransportManager() { return transportManager_.get(); }
+    const TransportManager* getTransportManager() const { return transportManager_.get(); }
     // Client-side M2 transport (trams, lifts) board/disembark check by proximity to the
     // transport's live position. Call once per tick with the player's current canonical
     // world position; safe to call whether or not any M2 transports are registered.
@@ -1307,6 +1312,10 @@ class GameHandler : public IConnectionState,
         outY = corpseX_;  // server X = canonical Y (west)
         return true;
     }
+    /** Corpse Z (up); only meaningful when getCorpseCanonicalPos() returns true. */
+    float getCorpseZ() const { return corpseZ_; }
+    /** Map the corpse is on, or 0 if no corpse data yet. */
+    uint32_t getCorpseMapId() const { return corpseMapId_; }
     /** Send CMSG_RECLAIM_CORPSE; noop if not a ghost or not near corpse. */
     void reclaimCorpse();
     void releaseSpirit();
@@ -1515,6 +1524,10 @@ class GameHandler : public IConnectionState,
     // NPC Gossip
     void interactWithNpc(uint64_t guid);
     void interactWithGameObject(uint64_t guid);
+    // Sends CMSG_TAXIQUERYAVAILABLENODES directly (what a real client sends
+    // when clicking a flight master, instead of CMSG_GOSSIP_HELLO) - see
+    // queryTaxiNodes() usage in headless_client/main.cpp for why.
+    void queryTaxiNodes(uint64_t guid);
     void selectGossipOption(uint32_t optionId);
     void selectGossipQuest(uint32_t questId);
     void acceptQuest();
@@ -2023,6 +2036,7 @@ class GameHandler : public IConnectionState,
     using TaxiPathEdge = MovementHandler::TaxiPathEdge;
     using TaxiPathNode = MovementHandler::TaxiPathNode;
     const std::unordered_map<uint32_t, TaxiNode>& getTaxiNodes() const;
+    const std::vector<TaxiPathEdge>& getTaxiPathEdges() const;
     bool isKnownTaxiNode(uint32_t nodeId) const;
     uint32_t getTaxiCostTo(uint32_t destNodeId) const;
     bool taxiNpcHasRoutes(uint64_t guid) const {

include/game/game_utils.hpp

@@ -2,11 +2,16 @@
 
 #include "game/expansion_profile.hpp"
 #include "core/application.hpp"
+#include <cstdlib>
+#include <string>
 
 namespace wowee {
 namespace game {
 
 inline bool isActiveExpansion(const char* expansionId) {
+    if (const char* env = std::getenv("WOWEE_ACTIVE_EXPANSION")) {
+        if (*env) return std::string(env) == expansionId;
+    }
     auto& app = core::Application::getInstance();
     auto* registry = app.getExpansionRegistry();
     if (!registry) return false;

include/game/movement_handler.hpp

@@ -130,6 +130,7 @@ class MovementHandler {
     };
 
     const std::unordered_map<uint32_t, TaxiNode>& getTaxiNodes() const { return taxiNodes_; }
+    const std::vector<TaxiPathEdge>& getTaxiPathEdges() const { return taxiPathEdges_; }
     // WotLK 3.3.5a TaxiNodes.dbc has 384 entries; the known-taxi bitmask
     // is 12 × uint32 = 384 bits. Node IDs outside this range are invalid.
     static constexpr uint32_t kMaxTaxiNodeId = 384;

include/game/protocol_constants.hpp

@@ -88,7 +88,8 @@ constexpr uint32_t SPELL_SHADOWFORM      = 15473;
 constexpr uint32_t RX_SILENCE_WARNING_MS       = 10000;  // 10 s
 constexpr uint32_t RX_SILENCE_CRITICAL_MS      = 15000;  // 15 s
 constexpr float    WARDEN_GATE_LOG_INTERVAL_SEC = 30.0f;
-constexpr float    CLASSIC_PING_INTERVAL_SEC    = 10.0f;
+// CMaNGOS classic/TBC treats pings under ~27s apart as overspeed pings.
+constexpr float    CLASSIC_PING_INTERVAL_SEC    = 30.0f;
 
 // ---------------------------------------------------------------------------
 // Heartbeat / area-trigger intervals (seconds)

include/game/social_handler.hpp

@@ -109,6 +109,10 @@ class SocialHandler {
     void cancelLogout();
     bool  isLoggingOut()        const { return loggingOut_; }
     float getLogoutCountdown()  const { return logoutCountdown_; }
+    // Distinct from isLoggingOut(), which goes back to false once the
+    // logout finishes - this stays true so callers (e.g. the headless
+    // client's shutdown loop) can tell "never logged out" from "done".
+    bool  isLogoutComplete()    const { return logoutComplete_; }
     bool  isLogoutToExit()      const { return exitAfterLogout_; }
 
     // Guild
@@ -368,6 +372,7 @@ class SocialHandler {
 
     // Logout
     bool  loggingOut_        = false;
+    bool  logoutComplete_    = false;
     bool  exitAfterLogout_   = false;
     float logoutCountdown_   = 0.0f;