40250 classic: parallel-dev checkpoint through increment 49 (W0 interface freeze)

Captures the uncommitted parallel-development work (increments 46-49) on the
40250 classic client port, folded into docs/CLIENT-GAP.md + CLIENT-GAP-FIX.md.

Increment 49 (W0 interface-freeze batch, Phase 1 prerequisite) lands the
cross-workflow shared-file scaffolding so the 4 Phase 1 workflows can run in
isolated worktrees without contention:

- entity_store.{h,cpp}: Entity gains empire/affect_flags/owner_vid/state_flags;
  new mut_spawn_full() (single-shot two-packet merge, §2.3), mut_ownership()
  (§2.5), mut_map_bgm() + take_bgm_dirty()/bgm_name()/bgm_volume() (§9.1),
  drain_dirty() (§2.1/§2.5 bare-field-update queue); mut_char_info() now stores
  empire; reset_for_map_change() clears m_dirty.
- m2_client.cpp: new bgm_changed(name, volume) signal; classic + m2dev pump
  loops drain drain_dirty() -> entity_info and take_bgm_dirty() -> bgm_changed;
  entity_dict() exposes the 4 new keys.
- classic/classic_parser.{h,cpp}: GC_MAIN_CHARACTER3_BGM /
  GC_MAIN_CHARACTER4_BGM_VOL route bgm_name/bgm_volume to mut_map_bgm() (was
  discarded); new m_pending_actor staging map (W1 fills §2.2 merge logic).
- project/bgm_director.gd (new) + game_scene.gd: BGM consumption split out of
  net_world.gd so W2/W4 don't collide; §8.6/§4.8 keybind convergence (digits
  1-4 -> quickslots 0-3, F1-F4 -> quickslots 4-7, Ctrl+1..9 -> _emote()).

Tests: cmake --build build clean; ctest 16/16; 15 GDScript regressions green
(netbridge, gamescene, netplay, p9, p10, p2b, p8, system_menu_ui, skill,
combat_fx, skill_fx, player_motion, char_status_ui, chat, inventory), no skips.

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

extension/src/net/classic/classic_parser.h

@@ -15,6 +15,7 @@
 #include <cstdint>
 #include <functional>
 #include <string>
+#include <unordered_map>
 #include <vector>
 
 namespace mtnet::classic {
@@ -27,6 +28,8 @@ struct CharSlot {
 	uint8_t st = 0, ht = 0, dx = 0, iq = 0;
 	uint32_t play_minutes = 0;
 	int32_t x = 0, y = 0;
+	int32_t addr = 0;
+	uint16_t port = 0;
 	uint16_t main_part = 0, hair_part = 0;
 	uint8_t skill_group = 0;
 	// Server requires this character to be renamed before entering the game.
@@ -62,6 +65,13 @@ public:
 	const std::string &login_failure() const { return m_login_failure; }
 	uint32_t login_key() const { return m_login_key; }     // GC_LOGIN_KEY (auth path)
 	uint8_t empire() const { return m_empire; }
+	void set_phase_name(const std::string &name) { m_phase_name = name; }
+	const std::string &last_error() const { return m_last_error; }
+	std::vector<uint8_t> drain_unhandled_headers() {
+		auto v = std::move(m_unhandled_headers);
+		m_unhandled_headers.clear();
+		return v;
+	}
 	std::vector<CharEvent> drain_char_events() {
 		auto v = std::move(m_char_events);
 		m_char_events.clear();
@@ -93,6 +103,10 @@ private:
 			uint32_t rkey);
 
 	EntityStore &m_world;
+	// §2.2 two-packet PC/NPC merge: GC_CHARACTER_ADD stages a bare Entity here
+	// keyed by vid; GC_CHAR_ADDITIONAL_INFO merges its fields and flushes the
+	// combined record via m_world.mut_spawn_full(). W1 owns the merge logic.
+	std::unordered_map<uint32_t, Entity> m_pending_actor;
 	std::vector<CharSlot> m_slots;
 	int m_slot_count = 0;
 	uint32_t m_handle = 0;
@@ -104,6 +118,9 @@ private:
 	int m_guild_make_requests = 0;
 	bool m_char_list_ready = false;
 	std::string m_login_failure;
+	std::string m_phase_name = "Offline";
+	std::string m_last_error;
+	std::vector<uint8_t> m_unhandled_headers;
 };
 
 } // namespace mtnet::classic