Panel/docs/architecture/RPC_STATUS_REPAIR_REPORT.md

RPC Status Repair Report

Purpose

This report documents the investigation and repair for the Panel message:

Error occurred on the remote host. Agent status: UNKNOWN. Agent status RPC unavailable.

The scope of this pass was status/RPC communication only. Steam Workshop, updater, scheduler, and unrelated module behavior were intentionally left unchanged.

Root Cause

The repository agents currently expose the structured server_status RPC on both Linux and Windows/Cygwin:

• Linux: Agent_Linux/ogp_agent.pl
• Windows/Cygwin: Agent-Windows/OGP64/OGP/ogp_agent.pl

The Panel also contains a fallback path for older or stale live agents where server_status is unavailable:

1. call remote_server_status() / agent server_status
2. call is_screen_running()
3. call agent exec() with an ss/netstat port probe

The fallback port probe was malformed. It shell-quoted the port before interpolating it into the grep regex. For port 2302, the Panel generated a pattern equivalent to:

[:.]'2302'([[:space:]]|$)

Normal ss and netstat output contains :2302 or .2302, not quotes around the port. Therefore the port fallback never matched listening game ports. If the live agent was stale, unreachable for server_status, or unable to report the screen session, the Panel had no working fallback and displayed UNKNOWN.

The fix builds the numeric listener regex directly and shell-quotes only the complete grep pattern:

[:.]2302([[:space:]]|$)

Status Flow

Step	File / Function	RPC / Handler	Purpose	Expected result
1	Panel/modules/gamemanager/server_monitor.php	get_agent_server_status()	Game Monitor asks for current state	structured status array
2	Panel/modules/gamemanager/start_server.php	get_agent_server_status(..., "STARTING")	Show post-start state	STARTING or ONLINE
3	Panel/modules/gamemanager/stop_server.php	get_agent_server_status(..., "STOPPING")	Verify stop result	STOPPING, OFFLINE, or ONLINE if stop failed
4	Panel/modules/gamemanager/restart_server.php	get_agent_server_status()	Verify restart state	active state or offline
5	Panel/modules/gamemanager/home_handling_functions.php	remote_server_status()	Primary structured status check	agent server_status hash
6	Panel/modules/gamemanager/home_handling_functions.php	is_screen_running()	Fallback managed session check	1, 0, or inconclusive
7	Panel/modules/gamemanager/home_handling_functions.php	exec()	Fallback agent-side game port probe	GSP_PORT_LISTENING or GSP_PORT_CLOSED

Status Decision Rules

Evidence	Panel status
Agent unreachable or no reliable check can be completed	UNKNOWN
Agent says process/session exists	ONLINE
Agent says configured game port is listening	ONLINE
Fallback is_screen_running returns true	ONLINE
Fallback exec port probe returns GSP_PORT_LISTENING	ONLINE
Agent/fallbacks confirm no session and no listening port	OFFLINE
Game query fails but session/process/port is known	ONLINE with query metadata unavailable

LGSL/GameQ/Steam query success is not a base online/offline signal. It is optional metadata.

Panel RPC Wrappers

Source: Panel/includes/lib_remote.php.

Panel wrapper	Agent RPC
rfile_exists()	rfile_exists
status_chk()	quick_chk
get_log()	get_log
remote_stop_server()	stop_server
remote_send_rcon_command()	send_rcon_command
remote_readfile()	readfile
remote_writefile()	writefile
remote_rebootnow()	rebootnow
steam()	steam
steam_cmd()	steam_cmd
fetch_steam_version()	fetch_steam_version
installed_steam_version()	installed_steam_version
automatic_steam_update()	automatic_steam_update
masterServerUpdate()	master_server_update
game_update_active()	game_update_active
start_file_download()	start_file_download
is_file_download_in_progress()	is_file_download_in_progress
uncompress_file()	uncompress_file
remote_dirlist()	dirlist
remote_dirlistfm()	dirlistfm
cpu_count()	cpu_count
renice_process()	renice_process
universal_start()	universal_start
lock_additional_home_files()	lock_additional_files
what_os()	what_os
discover_ips()	discover_ips
is_screen_running()	is_screen_running
remote_server_status()	server_status
mon_stats()	mon_stats
clone_home()	clone_home
remove_home()	remove_home
remote_restart_server()	restart_server
sudo_exec()	sudo_exec
exec()	exec
secure_path()	secure_path
get_chattr()	get_chattr
ftp_mgr()	ftp_mgr
compress_files()	compress_files
stop_fastdl()	stop_fastdl
start_fastdl()	start_fastdl
restart_fastdl()	restart_fastdl
fastdl_status()	fastdl_status
fastdl_get_aliases()	fastdl_get_aliases
fastdl_add_alias()	fastdl_add_alias
fastdl_del_alias()	fastdl_del_alias
fastdl_get_info()	fastdl_get_info
fastdl_create_config()	fastdl_create_config
agent_restart()	agent_restart
component_update()	component_update
scheduler_list_tasks()	scheduler_list_tasks
scheduler_del_task()	scheduler_del_task
scheduler_add_task()	scheduler_add_task
scheduler_edit_task()	scheduler_edit_task
remote_get_file_part()	get_file_part
shell_action()	shell_action
stop_update()	stop_update
remote_query()	remote_query
send_steam_guard_code()	send_steam_guard_code
steam_workshop()	steam_workshop
get_workshop_mods_info()	get_workshop_mods_info

Agent RPC Methods

Linux and Windows/Cygwin expose the same current status-critical methods:

Agent RPC	Linux	Windows/Cygwin	Notes
quick_chk	Yes	Yes	Agent reachability / key check
server_status	Yes	Yes	Structured status hash
is_screen_running	Yes	Yes	Managed screen/session fallback
exec	Yes	Yes	Generic command execution, used for port fallback
universal_start	Yes	Yes	Start server
stop_server	Yes	Yes	Stop server
restart_server	Yes	Yes	Restart server
get_log	Yes	Yes	Log retrieval

Linux also exposes renice_process and lock_additional_files, which are absent from Windows/Cygwin. Those are not involved in this status regression.

Mismatches Found

Mismatch	Impact
Documentation referenced Agent-Windows/ogp_agent.pl, but the current tracked file is Agent-Windows/OGP64/OGP/ogp_agent.pl.	Confuses future debugging and validation. Documentation was updated.
Panel fallback port regex inserted a shell-quoted port into a grep regex.	Prevented ss/netstat fallback from detecting running servers after server_status RPC was unavailable. Fixed.
Some non-status wrappers in lib_remote.php reference legacy RPC names whose current support should be checked before future work, such as steam and game_update_active.	Out of scope for this status repair.

Files Changed

• Panel/modules/gamemanager/home_handling_functions.php
• docs/features/STATUS_SYSTEM.md
• docs/modules/GAMEMANAGER.md
• docs/architecture/API_REFERENCE.md
• docs/architecture/PANEL_AGENT_COMMANDS.md
• docs/agents/WINDOWS_AGENT.md
• docs/architecture/RPC_STATUS_REPAIR_REPORT.md

Validation Commands

Run from repository root:

php -l Panel/modules/gamemanager/home_handling_functions.php
perl -c Agent_Linux/ogp_agent.pl
perl -c Agent-Windows/OGP64/OGP/ogp_agent.pl
rg -n "p=\\$port_arg|\\[:\\.\\]\\$p|Agent-Windows/ogp_agent\\.pl" \
  Panel/modules/gamemanager/home_handling_functions.php \
  docs/features/STATUS_SYSTEM.md \
  docs/modules/GAMEMANAGER.md \
  docs/architecture/API_REFERENCE.md \
  docs/architecture/PANEL_AGENT_COMMANDS.md \
  docs/agents/WINDOWS_AGENT.md

Live validation still requires a configured remote host:

1. Start or identify a known running server.
2. Confirm the game port is listening on the agent host with ss -lntu or netstat -an.
3. Open Game Monitor.
4. Confirm the server displays green ONLINE when either the screen/session or port is detected.
5. Stop the server.
6. Confirm the server displays OFFLINE only after session/process and port are gone.

Recommended Automated Tests

• Unit test gsp_agent_port_listening() command generation for port 2302; it must produce a grep pattern matching :2302 and not :'2302'.
• Mock remote_server_status() returning UNKNOWN and mock exec() returning GSP_PORT_LISTENING; get_agent_server_status() must return ONLINE.
• Mock remote_server_status() unavailable, is_screen_running() returning 1; get_agent_server_status() must return ONLINE.
• Mock all fallbacks returning closed/false; get_agent_server_status() may return OFFLINE.
• Integration smoke test against Linux and Windows/Cygwin agents for quick_chk, server_status, is_screen_running, and exec.