feat: Hot Runner Protocol — persistent process-based build/test providers

[frostebite]

Summary

Add support for persistent, actively-running Unity editor processes as build/test providers. Hot runners are long-lived processes that accept jobs immediately without cold-start overhead.

Motivation

Current providers follow a cold-start model: provision → clone → cache restore → build → tear down. Hot runners eliminate startup latency by keeping Unity editors warm and ready to accept work.

A hot runner is fundamentally a process-based provider — an actively running Unity editor (or other tool) that:

• Stays alive between jobs
• Accepts work via a registration/dispatch protocol
• Returns structured results
• Can run on any machine (local, server, cloud, container)

Core Concepts

Runner = Active Process + Transport

A hot runner is any process that:

1. Registers itself as available (with labels describing its capabilities)
2. Receives job dispatches via a transport protocol
3. Executes the job in its warm environment
4. Returns results (artifacts, test results, metrics, etc.)

Extensible Transport Registration

Any machine can become a labeled runner via pluggable transports:

Transport	Description	Use Case
GitHub Runner	Register as self-hosted GitHub Actions runner	Standard CI, existing infrastructure
WebSocket/SignalR	Real-time bidirectional connection to coordinator	Custom dashboards, game platforms
File-based	Watch shared directory for job files	Simple setups, NAS-based farms
Local Network	mDNS/Bonjour discovery + HTTP API	LAN build farms, office setups
Custom	Implement the runner interface in any language	Any transport

Editor Modes

Mode	Description
Ephemeral	Editor launches per job and exits (current behavior)
Persistent	Editor stays running, accepts multiple jobs
Hybrid	Pool of persistent editors, burst with ephemeral

Runner Labels

Runners self-describe with labels for job routing:

runnerLabels: unity-2022,linux,gpu,hot

Jobs are dispatched to runners matching required labels.

Runner Registration Protocol

{
  "type": "register",
  "labels": ["unity-2022", "linux", "gpu"],
  "capabilities": {
    "unityVersion": "2022.3.20f1",
    "platform": "StandaloneLinux64",
    "gpu": true
  }
}

Heartbeat, job dispatch, and result reporting follow the same JSON protocol over any transport.

Relationship to Other Features

• Incremental Sync Protocol (feat: Incremental Sync Protocol — cacheless workspace updates via git delta or direct input #793) — Hot runners can optionally use incremental sync to receive workspace updates without full clone/cache restore. This is a separate, composable protocol.
• Structured Build Output (feat: Generic Artifact System — multi-type output management, manifests, and processing pipelines #792) — Hot runners produce results via the generic artifact system.
• Test Workflow Engine (feat: Test Workflow Engine — suite definitions, taxonomy filters, structured results #788) — Hot runners can execute test suites with structured result reporting.

New Inputs

Input	Description
runnerTransport	Transport protocol (github, websocket, file, local-network, custom)
runnerEndpoint	Connection endpoint for the transport
runnerLabels	Comma-separated labels for job routing
editorMode	Editor lifecycle (ephemeral, persistent, hybrid)

Implementation Notes

• New module: src/model/orchestrator/runners/
• Runner interface as a protocol (like CLI provider) — any language can implement
• Hot editor communication via a small Unity-side package
• File-based transport is simplest: drop JSON job file, watch for result file
• GitHub runner transport uses existing actions/runner mechanism

---

Implementation

PR	Description	Status
#791	feat(orchestrator): hot runner protocol	Draft — 35 tests
game-ci/documentation#538	docs: hot runner protocol page	Draft
game-ci/game-ci-editor-tools#1	Hot runner worker — 5 transports	Complete

Tracking

• Next-Gen Features — #795
• LTS (v2.0.0) — #794
• Orchestrator: The Endgame — #810

[frostebite]

Implementing PR: #791 (feature/hot-runner-protocol)

[frostebite]

Editor Tools Companion Package

The hot runner protocol in unity-builder defines the orchestrator/client side — dispatching jobs, health monitoring, and transport management. But the server/worker side must run inside Unity itself.

The game-ci/unity-builder-editor-tools Unity package needs to implement:

• Runner registration — auto-register the editor as an available hot runner on domain reload
• Transport server — listen for incoming job requests (websocket/named-pipe/gRPC) matching the client protocol
• Job execution — execute build methods or test runs within the already-warm editor
• Status reporting — report state (idle/busy/unhealthy), memory usage, Library hash back to the orchestrator
• Health heartbeats — send periodic heartbeats at the configured health check interval
• Graceful lifecycle — handle shutdown and recycling requests from the orchestrator

Without this package, hot runners require manual setup. With it, any Unity editor instance can self-register as a hot runner worker.

See: https://github.com/game-ci/unity-builder-editor-tools

[frostebite]

Implementation Complete

PR #791 (orchestrator/client side) is fully implemented with:

• HotRunnerRegistry — In-memory + file persistence, runner expiration/cleanup
• HotRunnerHealthMonitor — Periodic health checking, state transitions (healthy/degraded/offline)
• HotRunnerDispatcher — Label-based routing, timeout + fallback to cold builds
• HotRunnerService — Full lifecycle orchestration
• 35 unit tests covering registry, health monitoring, dispatch, and service flows
• 7 action.yml inputs: hotRunnerEnabled, hotRunnerTransport, hotRunnerHost, hotRunnerPort, hotRunnerHealthInterval, hotRunnerMaxIdle, hotRunnerFallbackToCold

Editor-Tools Companion (game-ci/unity-builder-editor-tools PR #1)

The Unity editor-side worker is also fully implemented:

• 5 transports: Named Pipe, File-based, HTTP (always available), WebSocket (#if GAMECI_WEBSOCKETS), SignalR (#if GAMECI_SIGNALR)
• Registry-based TransportFactory for user extensibility
• Health reporting: memory usage, uptime, Library hash, job count
• Job execution: build jobs via BuildPipeline, test jobs via TestRunnerApi
• Auto-recycling after configurable max jobs
• 13 C# files across transport, models, settings, and server components (~2000+ lines)
• SignalR dependency installation guidance included in README

Documentation: game-ci/documentation#538 (12-hot-runner-protocol.mdx)