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. creates SERVER_STOPPED marker for autorestart handling
3. removes startup flag for <ip>-<port>
4. kills tracked PIDs (screen_pid, windows_pid, game_pid) if present
5. kills managed screen session
6. checks if the game port is still listening and kills the owning PID
7. verifies stop success (no managed session, no tracked running PID, no listening game port)

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