GSP-Agent-Windows/docs/PROCESS_MANAGEMENT.md

GSP Windows Agent Process Management

Workspace reference: GSP-WORKSPACE.md

The Windows agent manages customer servers through the Cygwin runtime and the OGP Perl agent.

Current model

• OGP64 is the Cygwin root for the maintained launcher
• process state is tracked through the agent runtime and PID files
• configured port validation is handled by server_status in OGP64/OGP/ogp_agent.pl
• manual startup and shutdown are handled by the root batch scripts
• Windows-specific user and service assumptions belong here, not in the Panel

Important files

• OGP64/agent_start.bat
• OGP64/agent_stop.bat
• OGP64/OGP/ogp_agent.pl
• OGP64/OGP/Cfg/

Rule

Keep startup and stop behavior visible and explicit. Failures should be reported in the same console when launched manually.

Port validation

Detailed status validation design:

• GSP_WINDOWS_AGENT_PORT_VALIDATION.md

Lifecycle tracking

The Windows agent now tracks per-home runtime metadata under:

• OGP64/OGP/runtime_status/pid-<home_id>.kv

Tracked fields include PID/session information used to stop the right process reliably:

• screen_pid
• windows_pid
• game_pid
• ip
• port

Stop escalation flow

When stop is requested, the agent now:

1. marks status hint as STOPPING
2. removes startup flag for <ip>-<port>
3. kills tracked PIDs (screen_pid, windows_pid, game_pid) if present
4. kills managed screen session
5. checks if the game port is still listening and kills the owning PID
6. verifies stop success (no managed session, no tracked running PID, no listening game port)
7. writes status hint STOPPED only after verification passes

The agent no longer creates or reads SERVER_STOPPED/Server_Stopped marker files for lifecycle control. Autorestart loop control now uses agent-owned runtime status hints (STARTING/STOPPING/STOPPED) instead of game-home marker files.

Restart behavior

Restart remains stop-first and now guards against duplicates:

• stop is attempted first
• waits 60 seconds
• verifies old instance is stopped before starting again
• returns stop failure if the old process/port is still active