feat: add ping interval override for improved job pickup performance

[jasonwbarnett]

Description

Problem: Buildkite agents poll for jobs every 10-20 seconds (server interval + jitter), causing significant delays for performance-sensitive workloads like dynamic pipelines where steps generate other steps. This can add 10-20 seconds of latency to each step, compounding across pipeline execution.

Solution: Add --ping-interval CLI flag and BUILDKITE_AGENT_PING_INTERVAL environment variable to override the server-specified ping interval, enabling faster job pickup (e.g., 5-10 seconds instead of 10-20 seconds).

Alternatives considered:

• Server-side configuration (would require Buildkite platform changes)
• WebSocket-based job delivery (major architectural change)
• Chose client-side override as it's backward compatible and gives users immediate control

Context

This addresses performance concerns with dynamic pipelines where job pickup latency significantly impacts overall pipeline execution time. The feature allows users to optimize for their specific use cases while maintaining server load protection through built-in safeguards.

Changes

• Core functionality: Add ping interval override with 2-second minimum safeguard
• Configuration: New PingInterval field in AgentStartConfig and AgentConfiguration
• Validation: Automatic clamping of values below 2 seconds with warning logs
• Testing: Comprehensive unit tests for validation logic and CLI configuration
• Documentation: Updated CLI help, README, technical docs, and CHANGELOG

CLI Help Output:

--ping-interval value    Override the server-specified ping interval in seconds (integer values only). 
                         The default of 0 uses the server-provided interval. Minimum value is 2 seconds 
                         (default: 0) [$BUILDKITE_AGENT_PING_INTERVAL]

Usage Examples:

# Faster job pickup (5-10 seconds instead of 10-20 seconds)
buildkite-agent start --ping-interval=5

# Environment variable
export BUILDKITE_AGENT_PING_INTERVAL=3
buildkite-agent start

# Invalid values are handled gracefully
buildkite-agent start --ping-interval=1    # Clamped to 2s with warning
buildkite-agent start --ping-interval=2.5  # Error: integer values only

Testing

• Tests have run locally (with go test ./...). Buildkite employees may check this if the pipeline has run automatically.
• Code is formatted (with go fmt ./...)

Test Coverage:

• TestAgentWorker_PingIntervalValidation: Validation logic, clamping, warning messages
• TestAgentStartConfig_PingInterval: CLI configuration mapping
• Manual testing: CLI flag parsing, environment variables, error handling

Disclosures / Credits

Claude Code implemented the majority of this feature including:

• Core ping interval validation and override logic
• Comprehensive unit test suite with edge cases
• Documentation updates across README, technical docs, and CHANGELOG
• Safeguard implementation (2-second minimum with warnings)
• Code refactoring to make validation logic testable

I provided the initial requirement, reviewed the implementation approach, and requested the 2-second minimum safeguard to protect server infrastructure. The solution design and technical implementation were done by Claude Code following Buildkite's coding conventions and patterns.