# Status System

## Current Goal

The status system should tell the truth about a server's state without depending on stale marker files or query success alone.

## Current Direction

The current codebase is moving toward agent-owned structured status.

Important files:

- `Panel/includes/lib_remote.php`
- `Panel/modules/gamemanager/home_handling_functions.php`
- `Panel/modules/gamemanager/server_monitor.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`

## Recommended State Model

| State | Meaning |
|---|---|
| `OFFLINE` | No managed session/process and no required port listening. |
| `STARTING` | Managed session/process exists but the required port is not ready yet. |
| `ONLINE` | Managed session/process exists and the required port is listening. |
| `STOPPING` | Stop is in progress and the session/process still exists. |
| `UNRESPONSIVE` | The server did not become ready in time or stop did not complete cleanly. |
| `UNKNOWN` | The agent cannot be reached or cannot determine state. |

## What Should Be Checked

The agent should check, in this order:

1. managed session or screen name
2. process or PID tree when available
3. required game port listening
4. optional query/RCON port listening
5. optional query metadata

## Known Problems To Remember

- LGSL/GameQ may fail for supported games, blocked ports, or slow startups.
- Marker files can become stale after crashes or power loss.
- A game can be online even if query metadata is temporarily unavailable.
- Some games need long startup windows, so timeouts must be configurable per game.

## Planned Improvement Shape

- make the agent the source of truth
- preserve optional query metadata
- use state hints for start/stop transitions
- expose clear messages for `STARTING` and `UNRESPONSIVE`
- add precise log excerpts when startup fails