# Companion Programs

Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)

## Current State

Companion programs are not yet a first-class managed system. Current behavior is mostly script-driven and game-specific.

Important references:

- `docs/decisions/0003-companion-programs.md`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
- `Panel/modules/config_games/schema_server_config.xml`

Current lifecycle hardening:

- Linux and Windows both prepare `_gsp_content/runtime/server_content.pids` under each server home.
- Stop and restart clean server-owned content PIDs before main server process escalation.
- Main game server PIDs stay in agent runtime metadata, not in the server-content PID registry.
- Windows imports legacy `_alsoRun.pid` entries into the server-content cleanup path for compatibility.
- New sidecars, bots, and hooks should use server-owned content runtime, not agent-global or customer-editable helper processes.

## What The System Needs To Do

- start companion apps with the server
- stop companion apps when the server stops
- restart companion apps when the server restarts
- track PIDs or handles
- log stdout/stderr
- avoid customer-editable privileged startup scripts

## Good Companion Examples

- BEC for Arma/DayZ
- B3
- Discord bots or bridges
- log watchers
- stats collectors
- anti-cheat helpers

## Recommended Shape

The system should be XML/admin-defined and agent-managed.

## Recommendation

Keep the design centralized and game-aware. Do not rely on one-off helper files as the source of truth.