Fix missing bridge env reconnect diagnostics

Author: pardeike

README.md

@@ -140,9 +140,13 @@ If you want a download-to-working walkthrough, use the
   name.
 - **Steam bridge games**: prefer `SteamManaged` launch. It resolves the Steam
   app manifest to the installed game executable, starts Steam if needed, and
-  launches the real game process with GABP environment variables. Use
-  `gabs games doctor <id>` to inspect a config and `gabs games repair <id>` to
-  convert an older `SteamAppId` launcher URL config.
+  launches the resolved executable with GABP environment variables. Some Steam
+  or platform-managed apps can still relaunch the final game process without
+  those variables; `games_status` reports that as
+  `process-bridge-environment-missing`. Use `gabs games doctor <id>` to inspect
+  a config, `gabs games repair <id>` to convert an older `SteamAppId` launcher
+  URL config, and `DirectPath` or `CustomCommand` when the final process does
+  not inherit the bridge environment.
 - **More than one AI session**: that is fine. GABS coordinates ownership per
   game with a short active-owner lease. You can hop between live sessions:
   `games_connect` takes over naturally after the previous session goes idle,
@@ -158,9 +162,10 @@ If you want a download-to-working walkthrough, use the
   `games_start` with `resetEndpoint: true` only after confirming the cache
   should be rotated for a new process.
 - **Confusing bridge state**: start with `games_status`. It compares the
-  runtime state and process environment where the OS allows it. If a Steam
-  launcher URL config reused old GABP environment, run
-  `gabs games repair <id>` to switch to managed Steam launch.
+  runtime state and process environment where the OS allows it. If
+  `diagnostics.code` is `process-bridge-environment-missing`, the running game
+  process is visible but not attachable through the expected GABP environment;
+  adjust the launch mode instead of retrying `games_connect`.
 
 ## How It Works
 

docs/AI_CLIENT_SETUP.md

@@ -92,10 +92,12 @@ Examples of `stopProcessName`:
 - Java-based FactorySim setups: `java`
 
 For Steam bridge games, prefer `SteamManaged`; it resolves the Steam app
-manifest to the installed executable and starts Steam if needed. For launcher
-URL modes such as `SteamAppId` and `EpicAppId`, `stopProcessName` is required.
-Without it, GABS can launch the game but cannot stop the real game process
-reliably.
+manifest to the installed executable and starts Steam if needed. Still verify
+`games_status`: if it reports `process-bridge-environment-missing`, the final
+game process did not inherit the bridge environment and the config should use
+`DirectPath` or `CustomCommand`. For launcher URL modes such as `SteamAppId`
+and `EpicAppId`, `stopProcessName` is required. Without it, GABS can launch the
+game but cannot stop the real game process reliably.
 
 ## What Success Looks Like
 

docs/CONFIGURATION.md

@@ -177,9 +177,12 @@ Best for Steam games with GABP bridges.
 ```
 You can find the App ID in the game's Steam store URL. GABS locates the Steam
 library, reads the app manifest, starts the Steam client if needed, launches the
-real game executable with GABP environment variables, and prepares
+resolved executable with GABP environment variables, and prepares
 `steam_appid.txt` when direct Steamworks startup requires it. Configured `args`
-are passed to the game in this mode.
+are passed to the game in this mode. If Steam or the platform relaunches the
+final game process without inheriting those variables, `games_status` reports
+`process-bridge-environment-missing`; use `DirectPath` or `CustomCommand` for a
+wrapper that the final process actually inherits from.
 
 Use `gabs games doctor <id>` to inspect the resolved executable and
 `gabs games repair <id>` to switch an older `SteamAppId` config to this mode.
@@ -205,8 +208,9 @@ bridge environment directly.
 In launcher-driven setups, an already-running platform launcher process can
 prevent GABS from proving that new environment variables reached the real game
 process. `games_status` reports whether the real game process environment is
-readable. For deterministic env and argument control, use `SteamManaged`,
-`DirectPath`, or `CustomCommand`. For an existing Steam launcher config, run
+readable. Prefer `SteamManaged` over launcher URL mode, but still verify the
+final process environment. If it reports `process-bridge-environment-missing`,
+use `DirectPath` or `CustomCommand`. For an existing Steam launcher config, run
 `gabs games repair <id>`.
 
 ### EpicAppId
@@ -470,8 +474,10 @@ mandatory. `SteamManaged` launches the resolved game executable directly, so
 4. Run `games_status` and inspect `diagnostics.code`, `diagnostics.message`,
    and `nextActions`; it can identify stale runtime state, runtime ownership,
    and whether the real game process environment is readable.
-5. For Steam launcher URL configs, run `gabs games repair <id>` to switch to
-   managed Steam launch.
+5. If `diagnostics.code` is `process-bridge-environment-missing`, the running
+   process is visible but cannot be attached through its environment. For Steam
+   launcher URL configs, run `gabs games repair <id>` first; if managed launch
+   still loses the environment, use `DirectPath` or `CustomCommand`.
 
 ### "Configuration not found"
 The config file is created automatically when you add your first game. If it's missing, run `gabs games add` to create a new one.

docs/DEPLOYMENT.md

@@ -309,5 +309,8 @@ not make the game-side bridge read `bridge.json`; use `games_connect` so GABS
 can prefer the running process environment. If `games_start` reports
 `endpoint_cache_in_use`, attach with `games_connect` or use `resetEndpoint:
 true` only after confirming the cached endpoint should be rotated. For Steam
-games that need deterministic environment injection, use `SteamManaged` or run
-`gabs games repair <id>` to convert an older `SteamAppId` config.
+games, prefer `SteamManaged` over launcher URL mode or run `gabs games repair
+<id>` to convert an older `SteamAppId` config. If `games_status` reports
+`process-bridge-environment-missing`, the final process did not inherit the
+bridge environment; use `DirectPath` or `CustomCommand` instead of retrying
+`games_connect`.

docs/SOLUTION_SUMMARY.md

@@ -7,7 +7,10 @@
 > support explicit active takeover with `games.connect {"forceTakeover": true}`.
 > Current Steam bridge games should use `SteamManaged`, which resolves the
 > installed Steam app executable and launches it directly with GABP environment.
-> `SteamAppId` remains as a legacy launcher URL mode.
+> `SteamAppId` remains as a legacy launcher URL mode. If a platform-managed
+> launch still drops the bridge environment before the final process starts,
+> `games_status` reports `process-bridge-environment-missing`; use `DirectPath`
+> or `CustomCommand` for that setup.
 
 ## Problem Analysis
 
@@ -150,7 +153,7 @@ type ProcessError struct {
 - ✅ **Serialized starting**: Only one process starting at a time
 - ✅ **Error handling**: Structured errors with context
 - ✅ **Steam/Epic games**: Proper legacy launcher vs directly managed process distinction
-- ✅ **SteamManaged games**: Steam apps can be launched as resolved executables with deterministic GABP environment injection
+- ✅ **SteamManaged games**: Steam apps can be launched as resolved executables with bridge environment injection, with status diagnostics when the final process does not inherit it
 
 **Status Reporting Examples**:
 - **With tracking**: "running (GABS is tracking the game process)"

internal/mcp/reconnect_test.go

@@ -225,6 +225,77 @@ func TestGamesConnectPrefersReadableProcessEnvironmentOverBridgeFile(t *testing.
 	}
 }
 
+func TestGamesConnectDoesNotUseBridgeFileWhenReadableProcessEnvironmentLacksEndpoint(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("process environment inspection is not supported on Windows")
+	}
+
+	tmpDir := t.TempDir()
+	writeBridgeJSONForTest(t, tmpDir, "adventure", unusedLocalPort(t), "bridge-file-token")
+
+	exe, err := os.Executable()
+	if err != nil {
+		t.Fatalf("failed to locate helper executable: %v", err)
+	}
+	cmd := exec.Command(exe, "-test.run=TestSharedRuntimeStateHelperProcess")
+	cmd.Env = append(os.Environ(), "GABS_HELPER_PROCESS=1")
+	if err := cmd.Start(); err != nil {
+		t.Fatalf("failed to start helper process: %v", err)
+	}
+	defer func() {
+		_ = cmd.Process.Kill()
+		_, _ = cmd.Process.Wait()
+	}()
+
+	runtimeState := process.RuntimeState{
+		GameID:   "adventure",
+		Status:   process.RuntimeStateStatusRunning,
+		OwnerPID: os.Getpid(),
+		GamePID:  cmd.Process.Pid,
+	}
+	if err := process.SaveRuntimeState("adventure", tmpDir, runtimeState); err != nil {
+		t.Fatalf("failed to write runtime state: %v", err)
+	}
+
+	gamesConfig := &config.GamesConfig{
+		Games: map[string]config.GameConfig{
+			"adventure": {
+				ID:         "adventure",
+				Name:       "AdventureGame",
+				LaunchMode: "SteamManaged",
+				Target:     "123456",
+			},
+		},
+	}
+
+	server := NewServerForTesting(util.NewLogger("error"))
+	server.SetConfigDir(tmpDir)
+	server.RegisterGameManagementTools(gamesConfig, 100*time.Millisecond, time.Second)
+
+	connectText := marshalMessage(t, server.HandleMessage(&Message{
+		JSONRPC: "2.0",
+		Method:  "tools/call",
+		ID:      json.RawMessage(`"connect-missing-process-env"`),
+		Params: map[string]interface{}{
+			"name": "games.connect",
+			"arguments": map[string]interface{}{
+				"gameId":  "adventure",
+				"timeout": 1,
+			},
+		},
+	}))
+
+	if !strings.Contains(connectText, `"isError":true`) {
+		t.Fatalf("expected connect to fail, got: %s", connectText)
+	}
+	if !strings.Contains(connectText, "running process environment is readable") || !strings.Contains(connectText, "does not contain GABP_SERVER_PORT/GABP_TOKEN") {
+		t.Fatalf("expected readable missing-env diagnosis, got: %s", connectText)
+	}
+	if strings.Contains(connectText, "Failed to connect to GABP server") || strings.Contains(connectText, "after 1s") {
+		t.Fatalf("connect should not dial the internal endpoint when process env is readable but missing, got: %s", connectText)
+	}
+}
+
 func TestGamesCallToolFailsFastAndStatusTurnsDisconnectedAfterBridgeDrop(t *testing.T) {
 	tmpDir, err := os.MkdirTemp("", "gabs-reconnect-disconnect")
 	if err != nil {

internal/mcp/state_diagnostics.go

@@ -64,9 +64,17 @@ func (s *Server) gameStateDiagnostics(game config.GameConfig, status string) map
 		message = "Stale runtime state was removed."
 	}
 
-	if (game.LaunchMode == "SteamAppId" || game.LaunchMode == "EpicAppId") && status != "stopped" && status != "stale-runtime-cleaned" && !processEnv.Present {
+	if runningStatusNeedsBridgeEnvironment(status) && readableProcessEnvLacksAttachableBridgeEndpoint(game, processEnv) {
+		code = "process-bridge-environment-missing"
+		severity = "warning"
+		message = processBridgeEnvironmentMissingMessage(game, processEnv)
+	}
+
+	if runningStatusNeedsBridgeEnvironment(status) && platformManagedLaunchModeNeedsVisibleBridgeEnvironment(game) && !processEnvBridgeEndpointUsableForGame(game, processEnv) {
 		if game.LaunchMode == "SteamAppId" {
 			warnings = append(warnings, "Could not verify GABP environment on the real game process; SteamAppId launcher URL mode can reuse stale environment from an already-running launcher. Run 'gabs games repair "+game.ID+"' to switch to managed Steam launch.")
+		} else if game.LaunchMode == "SteamManaged" {
+			warnings = append(warnings, "Could not verify GABP environment on the real game process; Steam-managed launch can still lose environment variables if the platform relaunches the app. Use DirectPath or CustomCommand when the final game process does not inherit the bridge environment.")
 		} else {
 			warnings = append(warnings, fmt.Sprintf("Could not verify GABP environment on the real game process; %s launchers can reuse stale environment from an already-running launcher.", game.LaunchMode))
 		}
@@ -97,6 +105,12 @@ func nextActionsForGameStateDiagnostics(game config.GameConfig, diagnostics map[
 	if diagnostics == nil {
 		return fallback
 	}
+	code, _ := diagnostics["code"].(string)
+	if code == "process-bridge-environment-missing" {
+		return []map[string]interface{}{
+			mcpNextAction("games_show", map[string]interface{}{"gameId": game.ID}, "Review the launch configuration; the running process is visible but does not expose an attachable GABP environment."),
+		}
+	}
 	if game.LaunchMode == "SteamAppId" {
 		status, _ := diagnostics["processEnvironment"].(map[string]interface{})
 		if present, _ := status["present"].(bool); !present {
@@ -109,6 +123,51 @@ func nextActionsForGameStateDiagnostics(game config.GameConfig, diagnostics map[
 	return fallback
 }
 
+func runningStatusNeedsBridgeEnvironment(status string) bool {
+	switch status {
+	case "running", "shared-running", "running-disconnected", "disconnected":
+		return true
+	default:
+		return false
+	}
+}
+
+func processEnvBridgeEndpointUsableForGame(game config.GameConfig, processEnv processEnvDiagnostic) bool {
+	if !processEnv.Present || processEnv.Port <= 0 || strings.TrimSpace(processEnv.Token) == "" {
+		return false
+	}
+	return processEnv.GameID == "" || processEnv.GameID == game.ID
+}
+
+func readableProcessEnvLacksAttachableBridgeEndpoint(game config.GameConfig, processEnv processEnvDiagnostic) bool {
+	if !platformManagedLaunchModeNeedsVisibleBridgeEnvironment(game) {
+		return false
+	}
+	if !processEnv.Readable || processEnv.PID <= 0 {
+		return false
+	}
+	return !processEnvBridgeEndpointUsableForGame(game, processEnv)
+}
+
+func platformManagedLaunchModeNeedsVisibleBridgeEnvironment(game config.GameConfig) bool {
+	switch game.LaunchMode {
+	case "SteamManaged", "SteamAppId", "EpicAppId":
+		return true
+	default:
+		return false
+	}
+}
+
+func processBridgeEnvironmentMissingMessage(game config.GameConfig, processEnv processEnvDiagnostic) string {
+	if processEnv.GameID != "" && processEnv.GameID != game.ID {
+		return fmt.Sprintf("The running process environment is readable, but GABS_GAME_ID is %q instead of %q. GABS will not attach using cached endpoint state.", processEnv.GameID, game.ID)
+	}
+	if processEnv.Present {
+		return "The running process environment is readable, but it does not contain a complete GABP_SERVER_PORT/GABP_TOKEN pair. GABS will not attach using cached endpoint state."
+	}
+	return "The running process environment is readable, but it does not contain GABP_SERVER_PORT/GABP_TOKEN. The game was not launched with the GABS bridge environment, or a launcher dropped it before the final process started."
+}
+
 func gameStateDiagnosticMessage(statusItem map[string]interface{}) string {
 	diagnostics, _ := statusItem["diagnostics"].(map[string]interface{})
 	if diagnostics == nil {

internal/mcp/status_regression_test.go

@@ -332,6 +332,71 @@ func TestGamesStatusIgnoresBridgeFileMismatchWhenProcessEnvironmentIsReadable(t
 	}
 }
 
+func TestGamesStatusWarnsWhenReadableProcessEnvironmentLacksEndpoint(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("process environment inspection is not supported on Windows")
+	}
+
+	tmpDir, err := os.MkdirTemp("", "gabs-status-missing-env")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	game := config.GameConfig{
+		ID:         "steam-managed-env-game",
+		Name:       "Steam Managed Env Game",
+		LaunchMode: "SteamManaged",
+		Target:     "123456",
+	}
+	gamesConfig := &config.GamesConfig{
+		Games: map[string]config.GameConfig{game.ID: game},
+	}
+
+	writeBridgeFileForStatusTest(t, tmpDir, game.ID, unusedLocalPort(t), "bridge-token")
+	exe, err := os.Executable()
+	if err != nil {
+		t.Fatalf("failed to locate test executable: %v", err)
+	}
+	cmd := exec.Command(exe, "-test.run=TestSharedRuntimeStateHelperProcess")
+	cmd.Env = append(os.Environ(), "GABS_HELPER_PROCESS=1")
+	if err := cmd.Start(); err != nil {
+		t.Fatalf("failed to start helper process: %v", err)
+	}
+	defer func() {
+		_ = cmd.Process.Kill()
+		_, _ = cmd.Process.Wait()
+	}()
+
+	runtimeState := process.RuntimeState{
+		GameID:   game.ID,
+		Status:   process.RuntimeStateStatusRunning,
+		OwnerPID: os.Getpid(),
+		GamePID:  cmd.Process.Pid,
+	}
+	if err := process.SaveRuntimeState(game.ID, tmpDir, runtimeState); err != nil {
+		t.Fatalf("failed to seed runtime state: %v", err)
+	}
+
+	server := NewServerForTesting(util.NewLogger("error"))
+	server.SetConfigDir(tmpDir)
+	server.RegisterGameManagementTools(gamesConfig, 100*time.Millisecond, time.Second)
+
+	statusText := marshalMessage(t, server.HandleMessage(toolCallMessage("status-missing-env", "games.status", game.ID)))
+	if !strings.Contains(statusText, `"code":"process-bridge-environment-missing"`) {
+		t.Fatalf("expected missing process bridge environment diagnosis, got: %s", statusText)
+	}
+	if !strings.Contains(statusText, "Steam-managed launch can still lose environment variables") {
+		t.Fatalf("expected SteamManaged warning, got: %s", statusText)
+	}
+	if strings.Contains(statusText, `"tool":"games_connect"`) {
+		t.Fatalf("status should not recommend games_connect when the running process env is readable but missing, got: %s", statusText)
+	}
+	if strings.Contains(statusText, "bridge-token") {
+		t.Fatalf("raw bridge token leaked in status response: %s", statusText)
+	}
+}
+
 func writeBridgeFileForStatusTest(t *testing.T, configDir, gameID string, port int, token string) string {
 	t.Helper()
 

internal/mcp/stdio_server.go

@@ -3291,6 +3291,10 @@ func (s *Server) cleanupRuntimeStateInternal(gameId string) {
 
 func (s *Server) adoptProcessBridgeEndpoint(game config.GameConfig, runtimeState *process.RuntimeState, current bridgeEndpoint) (bridgeEndpoint, bool) {
 	processEnv := s.inspectGameBridgeEnvironment(game, runtimeState)
+	return s.adoptProcessBridgeEndpointFromDiagnostic(game, processEnv, current)
+}
+
+func (s *Server) adoptProcessBridgeEndpointFromDiagnostic(game config.GameConfig, processEnv processEnvDiagnostic, current bridgeEndpoint) (bridgeEndpoint, bool) {
 	if !processEnv.Present || processEnv.Port <= 0 || strings.TrimSpace(processEnv.Token) == "" {
 		return current, false
 	}
@@ -3323,11 +3327,16 @@ func (s *Server) adoptProcessBridgeEndpoint(game config.GameConfig, runtimeState
 }
 
 func (s *Server) resolveConnectBridgeEndpoint(game config.GameConfig, runtimeState *process.RuntimeState) (bridgeEndpoint, error) {
-	endpoint, _ := s.adoptProcessBridgeEndpoint(game, runtimeState, bridgeEndpoint{})
+	processEnv := s.inspectGameBridgeEnvironment(game, runtimeState)
+	endpoint, _ := s.adoptProcessBridgeEndpointFromDiagnostic(game, processEnv, bridgeEndpoint{})
 	if endpoint.Port > 0 && strings.TrimSpace(endpoint.Token) != "" {
 		return endpoint, nil
 	}
 
+	if readableProcessEnvLacksAttachableBridgeEndpoint(game, processEnv) {
+		return bridgeEndpoint{}, fmt.Errorf("%s", processBridgeEnvironmentMissingMessage(game, processEnv))
+	}
+
 	_, port, token, err := config.ReadBridgeJSON(game.ID, s.configDir)
 	if err != nil {
 		return bridgeEndpoint{}, fmt.Errorf("no readable live process environment and internal bridge endpoint was unavailable: %w", err)