run/protocol/control.md

Run Control Contract

Control is the lightweight high-priority channel between run and platform.

Implemented Routes

• POST /api/v1/run/control/hello: registers run metadata and receives a platform-issued session token.
• POST /api/v1/run/control/heartbeat: reports status, capacity, and capability fingerprint using the active session token.
• POST /api/v1/run/control/events: opens a signed text/event-stream control channel. Platform sends small wake events such as control.ready, control.heartbeat, and job.changed; Run then claims durable jobs through the job channel.

Payloads

• RunHelloRequest: registration token, run ID, display name, version, status, platform, capability summary, and capacity summary.
• RunHelloResponse: session token, server time, polling hints, and feature flags.
• RunHeartbeatRequest: session token, version, status, capacity, and current capability fingerprint.
• RunHeartbeatResponse: accepted status, next heartbeat interval, and optional capability refresh request.
• RunControlStreamRequest: run ID, session token, and the last event sequence observed by Run.
• RunControlEvent: run ID, monotonic endpoint-local sequence, event type, server time, and reconnect hint.
• RunCapabilityReport: capability names and compact fingerprint metadata.
• RunCapacityReport: max jobs, active jobs, queued jobs, and local resource summary.

Rules

• Control payloads must be small.
• Control events wake Run only; they must not carry job assignments or execution input.
• Control must not carry logs, artifact chunks, or long job result bodies.
• Control must have priority over job execution, log upload, and artifact transfer.
• Heartbeat capacity summaries must remain metadata-only and must not mention or carry heavy channel payloads.

Deferred Channels

Durable log ingest, artifact chunk transfer, and the optional game client bridge remain separate channels. The job channel is separate from control and uses /api/v1/run/jobs/* routes.