# GSP Windows Agent Process Management

Workspace reference: [`GSP-WORKSPACE.md`](../../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`](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