Codex documentstion created

docs/agents/LINUX_AGENT.md

@@ -0,0 +1,109 @@
+# Linux Agent
+
+## Role
+
+`Agent_Linux/ogp_agent.pl` is the Linux execution agent for GSP. It is responsible for:
+
+- starting and stopping game servers
+- managing `screen` sessions
+- reading logs
+- running update/install tasks
+- handling scheduler jobs
+- performing query checks and status checks
+
+## Important Files
+
+- `Agent_Linux/ogp_agent.pl`
+- `Agent_Linux/startups/`
+- `Agent_Linux/includes/`
+- `Agent_Linux/php-query/`
+- `Agent_Linux/Cfg/`
+- `Agent_Linux/Schedule/`
+- `Agent_Linux/steamcmd/`
+- `Agent_Linux/systemd/`
+
+## Startup Logic
+
+The Linux agent creates a managed `screen` session per server.
+
+Key flow in `ogp_agent.pl`:
+
+- `universal_start_without_decrypt`
+- `create_screen_cmd`
+- `create_screen_cmd_loop`
+- `replace_OGP_Env_Vars`
+
+The agent builds the startup command from:
+
+- the game XML template
+- server parameters
+- mod data
+- control password
+- path variables
+
+The session name follows the OGP naming convention, for example:
+
+```text
+OGP_HOME_000000123
+```
+
+## Status Logic
+
+Relevant functions:
+
+- `is_screen_running_without_decrypt`
+- `get_screen_pid_without_decrypt`
+- `server_status_without_decrypt`
+- `verify_server_stopped_without_decrypt`
+
+The status implementation should check:
+
+- screen/session existence
+- PID or child process information when available
+- whether the game port is listening
+- whether query metadata can be fetched
+
+Marker files such as `SERVER_STOPPED` should not be treated as the final source of truth.
+
+## Logging
+
+Relevant function:
+
+- `get_log`
+
+The agent reads screen logs and may also copy a local log file into the game home. Logs should be treated as runtime output, not as a state store.
+
+## Scheduler
+
+Linux scheduler functions live in `ogp_agent.pl`:
+
+- `scheduler_dispatcher`
+- `scheduler_server_action`
+- `scheduler_log_events`
+- `scheduler_add_task`
+- `scheduler_del_task`
+- `scheduler_edit_task`
+- `scheduler_read_tasks`
+- `scheduler_stop`
+- `scheduler_list_tasks`
+
+The scheduler is agent-driven. Panel pages create or edit jobs, but the agent executes them.
+
+## Configuration Files
+
+Useful configuration and runtime areas:
+
+- `Agent_Linux/Cfg/`
+- `Agent_Linux/startups/`
+- `Agent_Linux/steamcmd/`
+- `Agent_Linux/systemd/`
+
+The agent also maintains screen logs and helper scripts inside its runtime area.
+
+## Linux-Specific Notes
+
+- The Linux agent uses `screen` and `sudo_exec_without_decrypt`.
+- It can resolve server ownership and screen users via helper functions such as `find_user_by_screen_id`.
+- It must remain portable across distro variants, so avoid assuming one exact init system or one exact binary path.
+- For Windows-targeted games running under Linux, Wine-related path conversion appears in startup path handling.
+