# 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 GSP Perl agent.

## Current model

- `GSP64` 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 `GSP64/GSP/gsp_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

- `GSP64/agent_start.bat`
- `GSP64/agent_stop.bat`
- `GSP64/GSP/gsp_agent.pl`
- `GSP64/GSP/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:

- `GSP64/GSP/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`

Server-owned content runtimes are tracked separately under each server home:

- `_gsp_content/hooks/`
- `_gsp_content/generated/`
- `_gsp_content/runtime/`
- `_gsp_content/runtime/server_content.pids`

The main game server PID must remain in `runtime_status/pid-<home_id>.kv`, not in `server_content.pids`. The server-content PID file is reserved for hook, sidecar, bot, watchdog, and generated content application PIDs owned by that server.

## Stop escalation flow

When stop is requested, the agent now:

1. marks status hint as `STOPPING`
2. removes startup flag for `<ip>-<port>`
3. cleans server-owned content PIDs from `_gsp_content/runtime/server_content.pids`, watchdogs before app PIDs
4. imports legacy `_alsoRun.pid` entries into the server-content PID registry when present
5. kills tracked main server PIDs (`screen_pid`, `windows_pid`, `game_pid`) if present
6. kills managed screen session
7. checks if the game port is still listening and kills the owning PID
8. verifies stop success (no managed session, no tracked running PID, no listening game port)
9. 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.

Legacy `_alsoRun.bat` is treated as compatibility input only. New sidecars, bots, and hooks should be represented as server-owned content runtime and recorded in `server_content.pids` so stop and restart can clean them reliably.

## 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