browser/openspec/changes/report-run-server-metrics/design.md

Context

Platform already stores signed metric batches and explicitly marks a server as run-metrics-pending only until its generated Run reports a sample. Run has the protocol client method but no collector or caller, even when an autonomous lifecycle has started a managed process.

Goals / Non-Goals

Goals:

• Report an immediate sample after the autonomous lifecycle and a refreshed sample after accepted heartbeats.
• Use only supervised-process state for online status and generic local resource measurements for utilization fields.
• Keep request timeouts bounded and failures non-fatal.

Non-Goals:

• Infer player count, max players, TPS, latency, or any SCUM-specific semantics.
• Make platform lifecycle projections authoritative for process state.
• Add a metric spool, alter the platform metrics route, or expose local filesystem paths.

Decisions

• The worker owns reporting because it owns the active registration session and calls the existing signed metric endpoint. A sample is sent once registration, reconciliation, and autonomous startup have completed, then after each successful heartbeat.
• Online is true only if a persisted managed process matching the generated Run's endpoint and server is still running according to its supervisor. If no matching process exists or it has exited, Run reports online=false; it never derives this fact from the platform's stale projection.
• A platform-independent collector reads generic host CPU, memory, and the filesystem containing the Run workspace. Collector failures omit the affected optional field rather than failing the sample. The values use percentages in the existing protocol fields.
• Each request uses a short timeout. Errors are logged as degraded reporting and the main worker continues; the next heartbeat retries with a fresh sample. This preserves the control/jobs/logs/artifacts channel boundaries.

Risks / Trade-offs

• [Host APIs vary by OS] → isolate collection behind a runtime collector and test it with a deterministic fake; unavailable fields remain omitted.
• [Run restart loses a prior sample] → report immediately after autonomous bootstrap and on every heartbeat; platform already retains accepted observations.
• [A stale process record] → ask the supervisor for current status before deriving online state.

Migration Plan

No persistence migration is needed. Existing deployed Runs continue showing pending until replaced; new Runs report on their first successful registration/startup cycle. Rolling back simply stops new samples while existing platform history remains valid.

Open Questions

• None.