feat(ha-config-bootstrap): implement ha_wait_for_heartbeat_or_timeout (task 3.4)

- sem_timedwait on heartbeat_seen semaphore with CLOCK_REALTIME deadline
- deadline = now + election_timeout_ms + xorshift64 jitter
- Returns CTRL_STANDBY on heartbeat arrival (calls ha_do_demote)
- Returns CTRL_ELECTING on timeout (caller drives election)
- Allows OPCode_heartbeat through dispatch gate in CTRL_INIT state
- 3 new unit tests: standby-on-heartbeat, electing-on-timeout, gate-allows-heartbeat
- 24 Tests 0 Failures in test_ha_startup suite

src/controller/ha.h

@@ -313,6 +313,25 @@ int bootstrap_config_if_needed(cluster_t *c);
  */
 int xce_probe_config_tag(const char *host, uint16_t port, uint64_t *tag_out);
 
+/*
+ * ha_wait_for_heartbeat_or_timeout: wait in CTRL_INIT for an incoming heartbeat.
+ *
+ * Blocks on sem_timedwait(&ha->heartbeat_seen, &deadline) where
+ *   deadline = now(CLOCK_REALTIME) + election_timeout_ms + xorshift64_jitter
+ *
+ * Returns CTRL_STANDBY  — heartbeat arrived; ha_do_demote() was called
+ *                         (role is now CTRL_STANDBY).
+ * Returns CTRL_ELECTING — deadline expired; caller must drive the election.
+ *
+ * The heartbeat handler posts heartbeat_seen only when role == CTRL_INIT.
+ * OPCode_heartbeat is allowed through ha_dispatch_gate() in CTRL_INIT state
+ * so that the primary's periodic heartbeat can reach the handler.
+ *
+ * Requirements: 1.1 (heartbeat → CTRL_STANDBY), 1.2 (timeout → CTRL_ELECTING).
+ * Boundary: Controller FSM (ha.c).
+ */
+ctrl_role_t ha_wait_for_heartbeat_or_timeout(ha_state_t *ha);
+
 /* ── P3-6: Test-only failover shim ────────────────────────────── */
 
 #ifdef XCE_TESTING