[jonbeckman]

Summary

The grokcast pilot showed that the xcode pool always falls back. The route job logged "no matching primary runner is online". The mayflower report gives the cause: kinhin registers macOS and Xcode runners only after a matching job is queued, so Routact never sees one while it routes. Linux has the same problem in a smaller form. kinhin keeps one warm runner, that runner is busy during a job, and no runner is listed for 18 to 65 seconds after a job and at the hourly warm-pool recycle.

A pool can now set heartbeat. Its value is the labels of a runner that shows only that the host is up. While any online runner has those labels, busy or not, the pool uses its primary, and the autoscaler starts a runner for the queued job.

"xcode": {
  "primary": "self-hosted,macOS,ARM64,xcode",
  "heartbeat": "self-hosted,kinhin-container",
  "fallback": [ ... ]
}

• A heartbeat pool cannot set primaries-required, because it does not count idle runners. This is a config error.
• A heartbeat pool cannot use claim, for the same reason. The route job fails with a config error.
• The README has a new section, "Runners that register on demand".

Testing

• npm run all: lint passes, dist/ is rebuilt, and 130 tests pass.
• New tests cover a heartbeat runner when no primary is registered, a busy heartbeat runner, no heartbeat runner online, the claim refusal, and parsing and rejecting the config.

---

Generated by Claude Code

[jonbeckman]

Closing this. The fix belongs in the runner host: RabinApps/kinhin#74 adds min_idle, which keeps a registered idle runner for each pool and image, macOS and Xcode included. With that, the existing primaries-required: 1 sees mayflower's runners, and Routact needs no new option.

---

Generated by Claude Code