browser/openspec/changes/make-run-runtime-state-authoritative/specs/run-runtime-state-authority/spec.md

ADDED Requirements

Requirement: Generated Run registration reconciles observed process state

When a generated Run registers for a bound server instance, the platform SHALL enqueue a scoped process.status reconciliation job when the stored server state says the game process is running or failed and no active lifecycle job already covers that server. The reconciliation job SHALL use the plugin-declared status action and the same scoped workspace metadata as normal lifecycle jobs.

Scenario: Stale running state is checked after manual Run startup

• WHEN a generated Run registers for a server whose stored state is running
• THEN the platform enqueues one process.status job for that server and Run endpoint

Scenario: Existing active lifecycle job avoids duplicate status checks

• WHEN a generated Run registers while the same server already has an active lifecycle job
• THEN the platform does not enqueue an additional status reconciliation job

Requirement: Run process status is authoritative for observed lifecycle state

The platform SHALL project terminal process.status results from Run into the server instance state. A Run-reported processState of running SHALL mark the server running; stopped or not-started SHALL mark it stopped; exited SHALL mark it failed unless the exit classification is an operator stop such as requested-stop, forced-stop, or already-stopped, in which case it SHALL mark the server stopped.

Scenario: Run reports no managed process

• WHEN a status reconciliation job succeeds with processState=not-started
• THEN the platform marks the server stopped instead of preserving stale running

Scenario: Run reports an unexpected exit

• WHEN a status reconciliation job succeeds with processState=exited and exitClassification=unexpected-exit
• THEN the platform marks the server failed

Scenario: Run reports a live process

• WHEN a status reconciliation job succeeds with processState=running
• THEN the platform marks the server running

Requirement: Lifecycle command state changes use Run execution facts

For lifecycle start and stop jobs, the platform SHALL use Run execution facts when projecting server state. A successful process.start result SHALL mark running only when Run reports processState=running; a successful process.stop result SHALL mark stopped when Run reports stopped, not-started, or an operator-stopped exited state.

Scenario: Start succeeds without a running process fact

• WHEN a process.start job succeeds but Run reports processState=stopped
• THEN the platform does not mark the server running

Scenario: Stop succeeds from an already-stopped process

• WHEN a process.stop job succeeds with processState=not-started
• THEN the platform marks the server stopped