[cosmosquark]

Summary

Adds an optional Sector Alpha agent inside AlphaGSM, plus a skippable first-run tour. The agent ships with the normal alphagsm program. Official agent traffic uses https://alphagsm-api.sector-alpha.net for enrollment, binding, ownership challenges, posted stats, the session socket, job polling, authorization, and results. Sign-in, accounts, and the public directory stay on https://sector-alpha.net. Another provider is selected only with --origin, and that saved origin is then used for every agent operation.

alphagsm agent enroll redeems a ten-minute enrollment code, registers managed servers that already have a public address, turns reporting on, and leaves management off. alphagsm agent run runs the agent in the foreground until you stop it or close the terminal. It opens one outbound WebSocket for presence and job wakes. If that socket cannot open, it uses the existing HTTPS job poll. Authorize and result posts stay on HTTPS. The client requires TLS 1.2 or newer and verified hostnames. No inbound management listener is opened.

Reporting, management, publication, and each status, start, stop, and restart action stay separate consents. Game setup, agent setup, agent bind, and the first-run tour leave reporting and management off and do not install a service.

Keeping the agent running

alphagsm agent run is enough for a foreground session. On Linux, persistence is a separate command:

• alphagsm agent install-service writes alphagsm.service for the current user (~/.config/systemd/user/ or $XDG_CONFIG_HOME/systemd/user/), enables it, and starts it. It returns at login. It stops at logout unless linger is already enabled. The installer prints that hint and does not run loginctl enable-linger.
• alphagsm agent install-service --system writes /etc/systemd/system/alphagsm.service, enables it for boot, and starts it as one operator account. The account is --service-user, otherwise SUDO_USER, otherwise USER. Root is rejected. The unit sets User, Group, HOME, and USER. Writing that directory needs root. The command does not call sudo.
• Both units run the invoked program as alphagsm agent run. ALPHAGSM_CONFIG_LOCATION is copied into the unit when it is set. The unit file contains no secrets.
• Only one scope can be installed. A second alphagsm agent run stops while the service holds the local lock. Running install-service again restarts the unit so a new enrollment is loaded.
• alphagsm agent uninstall-service disables and removes the selected unit and leaves the local enrollment in place. Add --system to remove the system unit.
• Windows and macOS refuse the installer and say to keep alphagsm agent run in the foreground. Ordinary commands do not import the Linux grp or pwd modules. Windows enrollment still fails closed until user-only credential ACLs exist. Local game commands are unaffected.

Binding, ports, and the first-run tour

Operators can use agent bind TAG, agent bind '*', or agent setup. Guided previews infer the game, advertised IP or hostname, player port, query port, name, and capacity, then register private bindings. Each game can use a distinct subdomain on the same machine. Fresh A/AAAA answers must match the machine's expected public addresses before hostname publication. --public-ip supports NAT and multiple addresses. check-endpoint TAG is the local query diagnostic.

Trackmania XML-RPC, Enshrouded query-only settings, and Arma headless roles do not infer a player listener. An explicit --connect-port asks the operator to confirm the actual game listener and NAT mapping.

Player ports are approved separately from query ports. The local primary port supplies the optional report connect_port. queryport remains the query endpoint. --connect-port overrides the public player port. Minecraft's shared player and query port follows a confirmed query override unless a distinct player mapping was explicitly approved.

A skippable first-run tour appears only on a bare launch with a terminal. Enter remembers a skip. --welcome replays it and --skip-welcome supports installation scripts. It offers local server creation, a command walkthrough, and optional Sector Alpha enrollment. Creation, setup, and opening the remote wizard each need a separate confirmation. It does not start a game, enable reporting or management, or install a service. Existing records, wildcard or count selectors, and reserved names, including agent and steam-auth, are rejected before dispatch.

Security

• Verified TLS 1.2 or newer, no credentialed redirects, no proxies, and no inbound management listener.
• Bounded DNS and native parsers, and a ten-second report deadline.
• Strict optional connect_port accepts only an integer from 1 to 65535, or null. Unknown fields are rejected.
• Credentials and the journal live outside game datastores, with mode 0700 directories and 0600 files.
• Public player-stat queries are Minecraft Java vanilla, Minecraft Paper, and Team Fortress 2. TeamSpeak directory listing is a website choice after the name check. Other games keep private reporting, permitted remote actions, and approved player endpoints.
• Remote control accepts status, start, stop, and restart only.

Docs

• First-run setup
• Sector Alpha agent
• Everyday commands
• README section "Optional Sector Alpha connection"
• DEVELOPERS section "Sector Alpha outbound agent and shared public queries"

Checks on this update

The previous GitHub Actions run failed lint (pylint exit 28: an import cycle and unidiomatic type checks) and the Windows binary (No module named 'grp'). This commit loads grp and pwd only when looking up a system-service account, and moves the TeamSpeak directory message into agent.config so that cycle is gone. Locally, bash ./lint.sh scored 10.00/10 with exit 0, and the agent unit tests passed (257), including a check that importing the service module does not load grp or pwd. The Actions run on this commit is the remaining confirmation.